@nilejs/client 0.0.3 → 1.0.1

package/dist/index.cjs

@@ -1,215 +1,367 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  buildFormData: () => buildFormData,
-  createNileClient: () => createNileClient,
-  sendUploadRequest: () => sendUploadRequest
-});
-module.exports = __toCommonJS(index_exports);
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// src/result.ts
+/**
+* A successful client result. `data` mirrors `value` so code written for
+* earlier clients keeps working. `message` is present only when the server sent one.
+*/
+function clientOk(value, message) {
+	return {
+		isOk: true,
+		isErr: false,
+		value,
+		error: null,
+		...message === void 0 ? {} : { message },
+		data: value
+	};
+}
+/**
+* A failed client result with a readable message and any data the server
+* attached to the failure. `data` stays null, as it was for earlier clients.
+*/
+function clientErr(error, details = null) {
+	return {
+		isOk: false,
+		isErr: true,
+		value: null,
+		error,
+		details,
+		data: null
+	};
+}
 // src/safe-try.ts
+/**
+* Gracefully handles both synchronous and asynchronous operations by returning a result object.
+* This replaces the need for external slang-ts dependency and avoids try/catch boilerplate.
+*
+* @param fn - The function to execute (sync or async)
+* @returns A result object containing either the value or the error
+*
+* @example
+* const { isOk, value, error } = await safeTry(() => fetch(url));
+*/
 function safeTry(fn) {
-  try {
-    const result = fn();
-    if (result instanceof Promise) {
-      return result.then(
-        (value) => ({
-          isOk: true,
-          value,
-          isErr: false,
-          error: null
-        })
-      ).catch(
-        (error) => ({
-          isOk: false,
-          value: null,
-          isErr: true,
-          error
-        })
-      );
-    }
-    return { isOk: true, value: result, isErr: false, error: null };
-  } catch (error) {
-    return { isOk: false, value: null, isErr: true, error };
-  }
+	try {
+		const result = fn();
+		if (result instanceof Promise) return result.then((value) => ({
+			isOk: true,
+			value,
+			isErr: false,
+			error: null
+		})).catch((error) => ({
+			isOk: false,
+			value: null,
+			isErr: true,
+			error
+		}));
+		return {
+			isOk: true,
+			value: result,
+			isErr: false,
+			error: null
+		};
+	} catch (error) {
+		return {
+			isOk: false,
+			value: null,
+			isErr: true,
+			error
+		};
+	}
 }
-
 // src/request.ts
-async function sendNileRequest(config, intent, service, action, payload, options = {}) {
-  const { timeout = config.timeout ?? 3e4, ...fetchOptions } = options;
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), timeout);
-  const requestResult = await safeTry(async () => {
-    const response = await fetch(`${config.baseUrl}/services`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...config.headers,
-        ...fetchOptions.headers
-      },
-      credentials: config.credentials,
-      body: JSON.stringify({
-        intent,
-        service,
-        action,
-        payload: payload ?? {}
-      }),
-      signal: controller.signal,
-      ...fetchOptions
-    });
-    clearTimeout(timeoutId);
-    const json = await response.json();
-    return json;
-  });
-  if (requestResult.isErr) {
-    return resolveError(requestResult.error);
-  }
-  const result = requestResult.value;
-  if (!result.status) {
-    return { error: result.message, data: result.data };
-  }
-  return { error: null, data: result.data };
+/** Send one action call; the deadline covers both fetch and reading its JSON body. */
+async function sendRequest(config, body, multipart, options) {
+	const { timeout = config.timeout ?? 3e4, headers, signal, ...fetchOptions } = options;
+	if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 2147483647) return clientErr("Action timeout must be a positive integer up to 2147483647 milliseconds.");
+	const controller = new AbortController();
+	const abort = () => controller.abort(signal?.reason);
+	if (signal?.aborted) abort();
+	else signal?.addEventListener("abort", abort, { once: true });
+	let timedOut = false;
+	const timeoutId = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, timeout);
+	try {
+		const requestResult = await safeTry(async () => {
+			const mergedHeaders = new Headers(config.headers);
+			new Headers(headers).forEach((value, key) => {
+				mergedHeaders.set(key, value);
+			});
+			if (multipart) mergedHeaders.delete("content-type");
+			else mergedHeaders.set("content-type", "application/json");
+			const json = await (await fetch(`${config.baseUrl.replace(/\/+$/, "")}/services`, {
+				...fetchOptions,
+				method: "POST",
+				headers: mergedHeaders,
+				credentials: fetchOptions.credentials ?? config.credentials,
+				body: body(),
+				signal: controller.signal
+			})).json();
+			if (json === null || typeof json !== "object" || !("status" in json) || typeof json.status !== "boolean" || !("message" in json) || typeof json.message !== "string" || !("data" in json)) throw new Error("Invalid Nile action response.");
+			return json;
+		});
+		if (requestResult.isErr) {
+			if (timedOut) return clientErr("Action timed out.");
+			if (signal?.aborted) return clientErr("Action cancelled.");
+			return resolveError(requestResult.error);
+		}
+		const result = requestResult.value;
+		if (!result.status) return clientErr(result.message, result.data ?? null);
+		return clientOk(result.data, result.message);
+	} finally {
+		clearTimeout(timeoutId);
+		signal?.removeEventListener("abort", abort);
+	}
+}
+/** JSON action calls preserve the server's message and failure data unchanged. */
+function sendNileRequest(config, intent, service, action, payload, options = {}) {
+	return sendRequest(config, () => JSON.stringify({
+		intent,
+		service,
+		action,
+		payload: payload ?? {}
+	}), false, options);
 }
-async function sendUploadRequest(config, service, action, files, fields, options = {}) {
-  const { timeout = config.timeout ?? 3e4, ...fetchOptions } = options;
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), timeout);
-  const formData = buildFormData(service, action, files, fields);
-  const requestResult = await safeTry(async () => {
-    const { "Content-Type": _ct, ...safeHeaders } = config.headers ?? {};
-    const { "Content-Type": _ct2, ...safeFetchHeaders } = fetchOptions.headers ?? {};
-    const response = await fetch(`${config.baseUrl}/services`, {
-      method: "POST",
-      headers: {
-        ...safeHeaders,
-        ...safeFetchHeaders
-      },
-      credentials: config.credentials,
-      body: formData,
-      signal: controller.signal,
-      ...fetchOptions
-    });
-    clearTimeout(timeoutId);
-    const json = await response.json();
-    return json;
-  });
-  if (requestResult.isErr) {
-    return resolveError(requestResult.error);
-  }
-  const result = requestResult.value;
-  if (!result.status) {
-    return { error: result.message, data: result.data };
-  }
-  return { error: null, data: result.data };
+/** Let the runtime set the multipart boundary; retain the same action Result contract. */
+function sendUploadRequest(config, service, action, files, fields, options = {}) {
+	return sendRequest(config, () => buildFormData(service, action, files, fields), true, options);
 }
+/**
+* Builds a FormData instance with RPC routing fields and file/field entries.
+* The server expects 'intent', 'service', 'action' as string fields.
+*/
 function buildFormData(service, action, files, fields) {
-  const formData = new FormData();
-  formData.append("intent", "execute");
-  formData.append("service", service);
-  formData.append("action", action);
-  if (fields) {
-    for (const [key, value] of Object.entries(fields)) {
-      formData.append(key, value);
-    }
-  }
-  for (const [key, value] of Object.entries(files)) {
-    if (Array.isArray(value)) {
-      for (const file of value) {
-        formData.append(key, file);
-      }
-    } else {
-      formData.append(key, value);
-    }
-  }
-  return formData;
+	const formData = new FormData();
+	formData.append("intent", "execute");
+	formData.append("service", service);
+	formData.append("action", action);
+	if (fields) for (const [key, value] of Object.entries(fields)) formData.append(key, value);
+	for (const [key, value] of Object.entries(files)) if (Array.isArray(value)) for (const file of value) formData.append(key, file);
+	else formData.append(key, value);
+	return formData;
 }
+/** Convert local transport errors to the same client failure shape. */
 function resolveError(error) {
-  let errorMsg = "An unknown error occurred";
-  if (error instanceof Error) {
-    errorMsg = error.name === "AbortError" ? "Request timed out" : error.message;
-  } else {
-    errorMsg = String(error);
-  }
-  return { error: errorMsg, data: null };
+	return clientErr(error instanceof Error ? error.message : String(error));
 }
-
 // src/create-client.ts
+/**
+* Creates a type-safe Nile client for interacting with backend services.
+*
+* @param config - The client configuration including baseUrl
+* @returns A factory object with invoke, explore, schema, and upload methods
+*
+* @example
+* const nile = createNileClient<ServicePayloads>({ baseUrl: "/api" });
+* const result = await nile.invoke({
+*   service: "tasks",
+*   action: "create",
+*   payload: { title: "Buy milk" }
+* });
+* if (result.isErr) {
+*   console.error(result.error);
+* } else {
+*   console.log(result.value);
+* }
+*/
 function createNileClient(config) {
-  return {
-    /** Invoke a service action through the backend engine pipeline */
-    invoke: async (params) => {
-      const { service, action, payload, fetchOptions } = params;
-      const result = await sendNileRequest(
-        config,
-        "execute",
-        service,
-        action,
-        payload,
-        fetchOptions
-      );
-      return result;
-    },
-    /** Discover available services and actions (supports "*" wildcard) */
-    explore: async (params) => {
-      const { service, action, fetchOptions } = params;
-      return await sendNileRequest(
-        config,
-        "explore",
-        service,
-        action,
-        {},
-        fetchOptions
-      );
-    },
-    /** Get action schemas as JSON Schema (supports "*" wildcard) */
-    schema: async (params) => {
-      const { service, action, fetchOptions } = params;
-      return await sendNileRequest(
-        config,
-        "schema",
-        service,
-        action,
-        {},
-        fetchOptions
-      );
-    },
-    /** Upload files to an action via multipart form-data */
-    upload: async (params) => {
-      const { service, action, files, fields, fetchOptions } = params;
-      return await sendUploadRequest(
-        config,
-        service,
-        action,
-        files,
-        fields,
-        fetchOptions
-      );
-    }
-  };
+	return {
+		/** Invoke a service action through the backend engine pipeline */
+		invoke: async (params) => {
+			const { service, action, payload, fetchOptions } = params;
+			return await sendNileRequest(config, "execute", service, action, payload, fetchOptions);
+		},
+		/** Discover available services and actions (supports "*" wildcard) */
+		explore: async (params) => {
+			const { service, action, fetchOptions } = params;
+			return await sendNileRequest(config, "explore", service, action, {}, fetchOptions);
+		},
+		/** Get action schemas as JSON Schema (supports "*" wildcard) */
+		schema: async (params) => {
+			const { service, action, fetchOptions } = params;
+			return await sendNileRequest(config, "schema", service, action, {}, fetchOptions);
+		},
+		/** Upload files to an action via multipart form-data */
+		upload: async (params) => {
+			const { service, action, files, fields, fetchOptions } = params;
+			return await sendUploadRequest(config, service, action, files, fields, fetchOptions);
+		}
+	};
+}
+// src/socket-client.ts
+/** Own a lazy Socket.IO connection with no offline write buffering or automatic invocation retries. */
+function createNileSocketClient(config) {
+	const timeout = config.timeout ?? 3e4;
+	if (!Number.isSafeInteger(timeout) || timeout < 1) throw new Error("Socket timeout must be positive");
+	let socket;
+	let connecting;
+	let closed = false;
+	const listeners = /* @__PURE__ */ new Set();
+	const pending = /* @__PURE__ */ new Set();
+	const fail = (error) => clientErr(error);
+	const settleCallback = (fn) => {
+		Promise.resolve().then(fn).catch(() => void 0);
+	};
+	const request = async (event, input) => {
+		const connected = await connect();
+		if (connected.isErr) return fail(connected.error);
+		const current = connected.value;
+		if (!current.connected || closed) return fail("Socket disconnected");
+		return new Promise((resolve) => {
+			let settled = false;
+			const finish = (result) => {
+				if (settled) return;
+				settled = true;
+				pending.delete(cancel);
+				clearTimeout(timer);
+				resolve(result);
+			};
+			const cancel = () => finish(fail("Socket disconnected"));
+			const timer = setTimeout(() => finish(fail("Socket acknowledgement timed out")), timeout);
+			pending.add(cancel);
+			current.emit(event, input, (result) => {
+				if (!result || typeof result !== "object" || !("error" in result) || !("data" in result)) {
+					finish(fail("Invalid socket response"));
+					return;
+				}
+				if (typeof result.error === "string") {
+					finish(clientErr(result.error, result.data));
+					return;
+				}
+				finish(clientOk(result.data));
+			});
+		});
+	};
+	const rejoin = async () => {
+		for (const listener of listeners) {
+			if (!listener.active) continue;
+			const result = await request("nile:receive", {
+				topic: listener.topic,
+				scope: listener.scope
+			});
+			if (result.isOk) {
+				listener.normalizedScope = result.value?.scope;
+				continue;
+			}
+			const message = result.error;
+			settleCallback(() => config.onSubscriptionError?.({
+				topic: listener.topic,
+				error: message
+			}));
+		}
+	};
+	const connect = () => {
+		if (closed) return Promise.resolve(fail("Socket client is closed"));
+		if (socket?.connected) return Promise.resolve(clientOk(socket));
+		if (connecting) return connecting;
+		connecting = import("socket.io-client").then(({ io }) => new Promise((resolve) => {
+			if (closed) {
+				resolve(fail("Socket client is closed"));
+				return;
+			}
+			const current = socket ?? io(config.baseUrl, {
+				path: config.path ?? "/socket.io",
+				autoConnect: false,
+				withCredentials: true,
+				timeout,
+				auth: (done) => {
+					Promise.resolve().then(() => typeof config.auth === "function" ? config.auth() : config.auth ?? {}).then(done).catch(() => done({}));
+				}
+			});
+			if (!socket) {
+				socket = current;
+				current.on("disconnect", () => {
+					for (const cancel of [...pending]) cancel();
+				});
+				current.on("connect", () => {
+					rejoin();
+				});
+				current.on("nile:message", (message) => dispatchMessage(message, listeners));
+			}
+			let settled = false;
+			const finish = (result) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				current.off("connect", ready);
+				current.off("connect_error", failed);
+				pending.delete(cancel);
+				resolve(result);
+			};
+			const ready = () => finish(clientOk(current));
+			const failed = () => finish(fail("Socket connection failed"));
+			const cancel = () => finish(fail("Socket client closed"));
+			const timer = setTimeout(() => finish(fail("Socket connection timed out")), timeout);
+			pending.add(cancel);
+			current.once("connect", ready);
+			current.once("connect_error", failed);
+			current.connect();
+		})).catch(() => fail("Could not initialize socket client")).finally(() => {
+			connecting = void 0;
+		});
+		return connecting;
+	};
+	return {
+		invoke: (input) => request("nile:invoke", input),
+		send: (input) => request("nile:send", input),
+		async receive(input) {
+			const listener = {
+				...input,
+				scope: input.scope,
+				onMessage: input.onMessage,
+				active: true
+			};
+			listeners.add(listener);
+			const result = await request("nile:receive", {
+				topic: input.topic,
+				scope: input.scope
+			});
+			if (result.isErr) {
+				listeners.delete(listener);
+				return fail(result.error);
+			}
+			listener.normalizedScope = result.value?.scope;
+			return clientOk({ unsubscribe: () => {
+				listener.active = false;
+				listeners.delete(listener);
+				const shared = [...listeners].some((item) => item.topic === listener.topic && stableScope(item.scope) === stableScope(listener.scope));
+				if (shared || closed) return Promise.resolve(clientOk({ subscribed: shared }));
+				return request("nile:unsubscribe", {
+					topic: listener.topic,
+					scope: listener.scope
+				});
+			} });
+		},
+		close() {
+			closed = true;
+			listeners.clear();
+			for (const cancel of [...pending]) cancel();
+			socket?.disconnect();
+			socket?.removeAllListeners();
+		}
+	};
+}
+/** Match scoped messages independently of object property insertion order. */
+function stableScope(scope) {
+	if (scope === void 0 || scope === null) return "null";
+	if (Array.isArray(scope)) return `[${scope.map(stableScope).join(",")}]`;
+	if (typeof scope === "object") return `{${Object.keys(scope).sort().map((key) => `${JSON.stringify(key)}:${stableScope(scope[key])}`).join(",")}}`;
+	return JSON.stringify(scope);
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  buildFormData,
-  createNileClient,
-  sendUploadRequest
-});
+/** Deliver messages only to listeners for the same validated topic and scope. */
+function dispatchMessage(message, listeners) {
+	if (!message || typeof message !== "object" || !("topic" in message)) return;
+	const scope = stableScope("scope" in message ? message.scope : void 0);
+	for (const listener of listeners) {
+		if (!listener.active || listener.topic !== message.topic) continue;
+		if (stableScope(listener.normalizedScope ?? listener.scope) !== scope) continue;
+		Promise.resolve().then(() => listener.onMessage(message)).catch(() => void 0);
+	}
+}
+exports.buildFormData = buildFormData;
+exports.createNileClient = createNileClient;
+exports.createNileSocketClient = createNileSocketClient;
+exports.sendUploadRequest = sendUploadRequest;
+
 //# sourceMappingURL=index.cjs.map