@nilejs/client 0.0.2 → 1.0.0

package/README.md

@@ -1,12 +1,12 @@
 # @nilejs/client
 
-A standalone, type-safe client for the [Nile](https://github.com/nile-js/nile) backend framework.
+A type-safe frontend client for [Nile Js](https://nile-js.github.io/nile/) backends.
 
 ## Features
 
 - **Type-safe:** Generates and consumes types from your Nile backend for full compile-time payload validation.
-- **Graceful Error Handling:** Uses the result pattern `{ error, data }` instead of throwing exceptions.
-- **Zero Runtime Dependencies:** Built on raw `fetch` for maximum compatibility (uses `slang-ts` for safety).
+- **Graceful Error Handling:** Returns the same Result pattern as the Nile Js backend (`isOk`, `isErr`, `value`, `error`) instead of throwing exceptions.
+- **Small:** HTTP calls use the platform `fetch`. The only runtime dependency is `socket.io-client`, for the socket client.
 - **Flexible:** Supports custom headers, credentials, and timeouts per request.
 
 ## Installation
@@ -38,16 +38,16 @@ const nile = createNileClient({
 ### 2. Invoke Actions
 
 ```typescript
-const { error, data } = await nile.invoke({
+const result = await nile.invoke({
   service: "tasks",
   action: "create",
   payload: { title: "Buy milk" },
 });
 
-if (error) {
-  console.error("Action failed:", error);
+if (result.isErr) {
+  console.error("Action failed:", result.error);
 } else {
-  console.log("Success:", data);
+  console.log("Success:", result.value);
 }
 ```
 
@@ -78,10 +78,18 @@ await nile.invoke({
 
 ```typescript
 // Explore services and actions
-const { data: services } = await nile.explore({ service: "*", action: "*" });
+const services = await nile.explore({ service: "*", action: "*" });
+
+if (services.isOk) {
+  console.log(services.value);
+}
 
 // Fetch action schemas
-const { data: schemas } = await nile.schema({ service: "tasks", action: "*" });
+const schemas = await nile.schema({ service: "tasks", action: "*" });
+
+if (schemas.isOk) {
+  console.log(schemas.value);
+}
 ```
 
 ## API
@@ -97,7 +105,12 @@ Returns a Nile client instance.
 
 ### Methods
 
-All methods return a `Promise<ClientResult<T>>` where `ClientResult<T>` is `{ error: string | null, data: T | null }`.
+All methods return a `Promise<ClientResult<T>>`. Calls never throw:
+
+- Success: `{ isOk: true, isErr: false, value: T, error: null, message? }`, where `message` is the server's success message for HTTP calls
+- Failure: `{ isOk: false, isErr: true, value: null, error: string, details }`, where `details` holds any data the server attached, such as validation issues. Network failures and timeouts arrive as failures too.
+
+Check `isErr` first, then read `error` or `value`. The older `data` field is still present as a deprecated alias (the value on success, `null` on failure) so existing code keeps working.
 
 - `invoke(params)`: Execute a specific service action.
 - `explore(params)`: Discover services/actions using wildcards.

package/dist/index.cjs

@@ -1,144 +1,386 @@
-"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, {
-  createNileClient: () => createNileClient
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/safe-try.ts
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region 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
+	};
+}
+//#endregion
+//#region 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
+//#endregion
+//#region src/request.ts
+/**
+* Handles JSON communication with the Nile /services endpoint.
+* Uses fetch + safeTry for crash safety and returns a Result that never throws.
+*/
 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) {
-    const error = requestResult.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 };
-  }
-  const result = requestResult.value;
-  if (!result.status) {
-    return { error: result.message, data: result.data };
-  }
-  return { error: null, data: result.data };
+	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);
+		return await response.json();
+	});
+	if (requestResult.isErr) return resolveError(requestResult.error);
+	const result = requestResult.value;
+	if (!result.status) return clientErr(result.message, result.data ?? null);
+	return clientOk(result.data, result.message);
 }
-
-// src/create-client.ts
+/**
+* Handles multipart form-data uploads to the Nile /services endpoint.
+* Builds a FormData body with RPC routing fields (intent, service, action),
+* user-provided fields, and file attachments.
+*
+* Content-Type header is intentionally omitted so the runtime sets the
+* correct multipart boundary automatically.
+*/
+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);
+		return await response.json();
+	});
+	if (requestResult.isErr) return resolveError(requestResult.error);
+	const result = requestResult.value;
+	if (!result.status) return clientErr(result.message, result.data ?? null);
+	return clientOk(result.data, result.message);
+}
+/**
+* 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;
+}
+/** Resolve error from safeTry into a ClientResult */
+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 clientErr(errorMsg);
+}
+//#endregion
+//#region 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, ...options } = params;
-      const result = await sendNileRequest(
-        config,
-        "execute",
-        service,
-        action,
-        payload,
-        options
-      );
-      return result;
-    },
-    /** Discover available services and actions (supports "*" wildcard) */
-    explore: async (params) => {
-      const { service, action, ...options } = params;
-      return await sendNileRequest(
-        config,
-        "explore",
-        service,
-        action,
-        {},
-        options
-      );
-    },
-    /** Get action schemas as JSON Schema (supports "*" wildcard) */
-    schema: async (params) => {
-      const { service, action, ...options } = params;
-      return await sendNileRequest(
-        config,
-        "schema",
-        service,
-        action,
-        {},
-        options
-      );
-    }
-  };
+	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);
+		}
+	};
+}
+//#endregion
+//#region 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();
+		}
+	};
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  createNileClient
-});
+/** 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);
+}
+/** 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);
+	}
+}
+//#endregion
+exports.buildFormData = buildFormData;
+exports.createNileClient = createNileClient;
+exports.createNileSocketClient = createNileSocketClient;
+exports.sendUploadRequest = sendUploadRequest;
+
 //# sourceMappingURL=index.cjs.map