lissa 1.0.6 → 1.1.0

package/README.md

@@ -135,6 +135,8 @@ Checkout https://developer.mozilla.org/en-US/docs/Web/API/RequestInit for availa
 | paramsSerializer   | "simple", "extended" or Function   | "simple"  | How to serialize the query params
 | urlBuilder         | "simple", "extended" or Function   | "simple"  | How to build the final fetch url from the defined "baseURL" and "url"
 | responseType       | "json", "text", "file" or "raw"    | "json"    | The type of data that the server will respond with
+| replacer           | Function or Array                  | undefined | A function or array to transform values during JSON.stringify
+| reviver            | Function                           | undefined | A function to transform values during JSON.parse
 | timeout            | number                             | undefined | Specify the number of milliseconds before the request gets aborted
 | signal             | AbortSignal                        | undefined | Cancel/Abort running requests
 | body               | object, buffer, stream, file, etc. | undefined | Request body
@@ -150,6 +152,41 @@ Set the urlBuilder option to "simple", "extended" or a custom build function.
 
 Make sure to not forget a needed slash using "simple". If using "extended" be careful with leading and trailing slashes in urls, the baseURL and also with sub paths in the baseURL. For example `new URL("todos", "http://api.example.com/v2")` and `new URL("/todos", "http://api.example.com/v2/")` both results in a fetch to `"http://api.example.com/todos"`. Only `new URL("todos", "http://api.example.com/v2/")` will result in a fetch to the expected `"http://api.example.com/v2/todos"`.
 
+#### replacer option
+The replacer option allows you to control how values are stringified when sending JSON data. It works exactly like the second parameter of JSON.stringify(). You can provide either a function to transform values or an array to filter properties.
+
+```js
+// Using a function to filter out private properties
+const lissa = Lissa.create({
+  baseURL: "https://api.example.com",
+  replacer: (key, value) => {
+    if (key.startsWith('_')) return undefined; // Exclude private properties
+    return value;
+  }
+});
+```
+
+#### reviver option
+The reviver option allows you to transform values when parsing JSON responses. It works exactly like the second parameter of JSON.parse(). This is particularly useful for converting ISO date strings back into Date objects or handling other custom data types.
+
+```js
+// Using a reviver to convert ISO date strings to Date objects
+const lissa = Lissa.create({
+  baseURL: "https://api.example.com",
+  reviver: (key, value) => {
+    // Check if value is an ISO 8601 date string
+    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/.test(value)) {
+      return new Date(value);
+    }
+    return value;
+  }
+});
+
+const { data } = await lissa.get("/events");
+// data.createdAt is now a Date object instead of a string
+console.log(data.createdAt instanceof Date); // true
+```
+
 ### `result` Object/Error
 
 Every request returns a promise which gets fulfilled into a result object or rejected into a result error.
@@ -682,6 +719,69 @@ publicClient.use(Lissa.dedupe());
 
 See the `examples/` directory for more usage examples, including browser-specific code and advanced plugin usage.
 
+### Using Reviver to Convert Date Strings
+
+A common use case for the reviver function is to automatically convert ISO date strings back into JavaScript Date objects when receiving API responses.
+
+```js
+import Lissa from "lissa";
+
+// Create a reviver function that detects ISO 8601 date strings
+function dateReviver(key, value) {
+  // Pattern to match ISO 8601 date strings like "2026-07-01T12:34:56.789Z"
+  const isoDatePattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/;
+
+  if (typeof value === 'string' && isoDatePattern.test(value)) {
+    return new Date(value);
+  }
+
+  return value;
+}
+
+// Create a Lissa instance with the reviver
+const lissa = Lissa.create({
+  baseURL: "https://api.example.com",
+  reviver: dateReviver
+});
+
+// Example API response that contains date strings:
+// {
+//   "id": 123,
+//   "title": "Meeting",
+//   "createdAt": "2026-07-01T10:00:00.000Z",
+//   "updatedAt": "2026-07-01T15:30:00.000Z",
+//   "participants": [
+//     { "name": "Alice", "joinedAt": "2026-07-01T10:05:00.000Z" },
+//     { "name": "Bob", "joinedAt": "2026-07-01T10:10:00.000Z" }
+//   ]
+// }
+
+const { data: meeting } = await lissa.get("/meetings/123");
+
+// All date strings are automatically converted to Date objects
+console.log(meeting.createdAt instanceof Date); // true
+console.log(meeting.updatedAt instanceof Date); // true
+console.log(meeting.createdAt.toLocaleDateString()); // "7/1/2026"
+
+// Works with nested objects too
+console.log(meeting.participants[0].joinedAt instanceof Date); // true
+
+// You can now use Date methods directly
+const duration = meeting.updatedAt - meeting.createdAt;
+console.log(`Meeting lasted ${duration / 1000 / 60} minutes`);
+
+// The reviver can also be set per-request
+const { data: event } = await lissa.get("/events/456", {
+  reviver: (key, value) => {
+    // Custom reviver for this specific request
+    if (key === "startDate" || key === "endDate") {
+      return new Date(value);
+    }
+    return value;
+  }
+});
+```
+
 ## Browser Support
 
 Lissa works in all modern browsers that support the following APIs:

package/lib/core/defaults.js

@@ -13,6 +13,8 @@ export default {
 	'paramsSerializer': 'simple',
 	'urlBuilder': 'simple',
 	'responseType': 'json',
+	'replacer': undefined,
+	'reviver': undefined,
 
 	'get': basic(),
 	'post': basic(),

package/lib/core/request.js

@@ -72,6 +72,14 @@ export default class LissaRequest extends OpenPromise {
 		return this.#addOptions({ body });
 	}
 
+	reviver(reviver) {
+		return this.#addOptions({ reviver });
+	}
+
+	replacer(replacer) {
+		return this.#addOptions({ replacer });
+	}
+
 	timeout(timeout) {
 		return this.#addOptions({ timeout });
 	}
@@ -95,7 +103,7 @@ export default class LissaRequest extends OpenPromise {
 	#addOptions(options) {
 		if (this.#locked) {
 			console.warn(new Error('Request options cannot be changed anymore after execution start!'));
-			return;
+			return this;
 		}
 
 		if (options.headers) options.headers = new Headers(options.headers);
@@ -162,13 +170,15 @@ export default class LissaRequest extends OpenPromise {
 				options.headers.set('Content-Type', 'application/x-www-form-urlencoded');
 			}
 			else if (options.body.constructor === Object) {
-				options.body = JSON.stringify(options.body);
+				options.body = JSON.stringify(options.body, options.replacer);
 			}
 		}
 		else {
 			options.headers.delete('Content-Type');
 		}
 
+		delete options.replacer;
+
 		if (options.timeout) {
 			if (options.signal) {
 				options.signal = AbortSignal.any([
@@ -183,8 +193,8 @@ export default class LissaRequest extends OpenPromise {
 			delete options.timeout;
 		}
 
-		let baseURL, url, params, urlBuilder, adapter;
-		({ baseURL, url, params, urlBuilder, adapter, ...options } = options);
+		let baseURL, url, params, urlBuilder, adapter, reviver;
+		({ baseURL, url, params, urlBuilder, adapter, reviver, ...options } = options);
 
 		const fetchUrl = ((
 			baseURL,
@@ -204,8 +214,8 @@ export default class LissaRequest extends OpenPromise {
 
 		// Actual fetch
 		let returnValue = adapter === 'xhr'
-			? await this.#executeXhr({ url: new URL(fetchUrl), ...options })
-			: await this.#executeFetch({ url: new URL(fetchUrl), ...options });
+			? await this.#executeXhr({ url: new URL(fetchUrl), reviver, ...options })
+			: await this.#executeFetch({ url: new URL(fetchUrl), reviver, ...options });
 
 		returnValue.options = $options;
 
@@ -228,7 +238,7 @@ export default class LissaRequest extends OpenPromise {
 		return returnValue;
 	}
 
-	async #executeFetch({ url, responseType, onUploadProgress, onDownloadProgress, ...options }) {
+	async #executeFetch({ url, responseType, onUploadProgress, onDownloadProgress, reviver, ...options }) {
 		let request = { url, options };
 
 		for (const hook of this.#lissa.beforeFetchHooks) {
@@ -297,7 +307,7 @@ export default class LissaRequest extends OpenPromise {
 						if (!data) break;
 
 						try {
-							data = JSON.parse(data);
+							data = JSON.parse(data, reviver);
 						}
 						catch (error) {
 							data = null;
@@ -326,7 +336,7 @@ export default class LissaRequest extends OpenPromise {
 		return returnValue;
 	}
 
-	async #executeXhr({ url, ...options }) {
+	async #executeXhr({ url, reviver, ...options }) {
 		let request = { url, options };
 
 		for (const hook of this.#lissa.beforeFetchHooks) {
@@ -377,7 +387,11 @@ export default class LissaRequest extends OpenPromise {
 
 		if (options.signal) options.signal.addEventListener('abort', () => xhr.abort());
 
-		xhr.responseType = options.responseType === 'raw' || options.responseType === 'file' ? 'blob' : options.responseType;
+		xhr.responseType = options.responseType === 'json'
+			? 'text'
+			: options.responseType === 'raw' || options.responseType === 'file'
+				? 'blob'
+				: options.responseType;
 
 		if (options.onUploadProgress) {
 			xhr.upload.addEventListener('progress', (evt) => {
@@ -404,6 +418,16 @@ export default class LissaRequest extends OpenPromise {
 			returnValue.status = response.status;
 			returnValue.data = response.body;
 
+			if (options.responseType === 'json' && response.body) {
+				try {
+					returnValue.data = JSON.parse(response.body, reviver);
+				}
+				catch (error) {
+					returnValue.data = null;
+					console.error(error);
+				}
+			}
+
 			if (options.responseType === 'file') {
 				const type = response.headers.get('Content-Type');
 				const filename = getFilenameFromContentDisposition(response.headers.get('Content-Disposition'));

package/lib/index.d.ts

@@ -53,6 +53,8 @@ export type LissaOptionsInit = Omit<RequestInit, 'method' | 'body'> & {
 	paramsSerializer?: 'simple' | 'extended' | ((params: Params) => string);
 	urlBuilder?: 'simple' | 'extended' | ((url: string, baseURL: string) => string | URL);
 	responseType?: 'json' | 'text' | 'file' | 'raw';
+	replacer?: (this: any, key: string, value: any) => any | (string | number)[];
+	reviver?: (this: any, key: string, value: any) => any;
 	timeout?: number;
 	onUploadProgress?: (uploaded: number, total: number) => void;
 	onDownloadProgress?: (downloaded: number, total: number) => void;
@@ -193,6 +195,20 @@ export declare class LissaRequest<RT = ResultValue<ResultData>> extends Promise<
 	 */
 	body(body: BodyInit | JsonStringifyableObject): LissaRequest<RT>;
 
+	/**
+	 * Set a replacer function or array to transform values during JSON.stringify
+	 *
+	 * Works like the second parameter of JSON.stringify()
+	 */
+	replacer(replacer: (this: any, key: string, value: any) => any | (string | number)[]): LissaRequest<RT>;
+
+	/**
+	 * Set a reviver function to transform values during JSON.parse
+	 *
+	 * Works like the second parameter of JSON.parse()
+	 */
+	reviver(reviver: (this: any, key: string, value: any) => any): LissaRequest<RT>;
+
 	/**
 	 * Set request timeout in milliseconds
 	 *

package/lib/utils/helper.js

@@ -22,7 +22,12 @@ export function deepMerge(...objects) {
 	let merged;
 
 	for (const obj of objects) {
-		if (obj == null) continue;
+		if (obj === undefined) continue;
+
+		if (obj === null) {
+			merged = obj;
+			continue;
+		}
 
 		if (obj instanceof AbortSignal) {
 			if (!merged) merged = obj;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lissa",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "A lightweight, extensible HTTP client for modern JavaScript applications with fluent api syntax, hooks, plugins and more.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",