@randajan/api-kit 2.0.0 → 3.0.0

package/dist/cjs/index.cjs

@@ -20,17 +20,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Api: () => Api,
-  ApiError: () => ApiError,
   Fetch: () => Fetch,
+  FetchError: () => FetchError,
+  HttpError: () => HttpError,
   createApi: () => server_default,
   createFetch: () => client_default
 });
 module.exports = __toCommonJS(index_exports);
 
 // <define:__slib_info>
-var define_slib_info_default = { isBuild: true, name: "@randajan/api-kit", description: "A lightweight wrapper around fetch that always returns a structured JSON response, handling errors and network issues gracefully", version: "1.2.0", author: { name: "Jan Randa", email: "jnranda@gmail.com", url: "https://www.linkedin.com/in/randajan/" }, env: "development", mode: "web", port: 3e3, dir: { root: "C:\\dev\\lib\\api-kit", dist: "dist" } };
+var define_slib_info_default = { isBuild: true, name: "@randajan/api-kit", description: "A lightweight wrapper around fetch that always returns a structured JSON response, handling errors and network issues gracefully", version: "2.0.0", author: { name: "Jan Randa", email: "jnranda@gmail.com", url: "https://www.linkedin.com/in/randajan/" }, env: "development", mode: "web", port: 3e3, dir: { root: "C:\\dev\\lib\\api-kit", dist: "dist" } };
 
-// src/arc/class/ApiError.js
+// src/arc/class/FetchError.js
 var import_props = require("@randajan/props");
 
 // src/arc/tool.js
@@ -57,44 +58,34 @@ var doFn = (any) => isFn(any) ? any() : any;
 var isProm = (any) => any instanceof Promise;
 var isErr = (any) => any instanceof Error;
 
-// src/arc/class/ApiError.js
-var ApiError = class _ApiError extends Error {
-  static create(code, message, httpStatusCode = 400, remoteStack = void 0) {
-    return new _ApiError(code, message, httpStatusCode, remoteStack);
-  }
+// src/arc/class/FetchError.js
+var FetchError = class _FetchError extends Error {
   static is(any) {
-    return any instanceof _ApiError;
+    return any && any instanceof _FetchError;
   }
-  static to(code, any, httpStatusCode = 500) {
-    if (_ApiError.is(any)) {
-      return any;
-    }
-    const msg = toStr(any?.message || any) || "Unknown";
-    const apierr = _ApiError.create(code, msg, httpStatusCode);
-    return (0, import_props.solid)(apierr, "stack", any?.stack);
+  static code(code, message, opt = {}) {
+    opt.code = code;
+    return new _FetchError(message, opt);
   }
-  constructor(code, message, httpStatusCode = 400, remoteStack = void 0) {
-    super(message);
+  constructor(message, options = {}) {
+    const { code, ...opt } = options || {};
+    super(message, opt);
     (0, import_props.safe)(this, {}, "code", (t, f) => mrgStr(t, f, "."));
-    (0, import_props.solid)(this, "httpStatusCode", httpStatusCode ?? 400, true);
-    (0, import_props.solid)(this, "remoteStack", remoteStack);
     this.rise(code);
   }
-  rise(code = 0) {
-    this.code = code || 0;
-    return this;
-  }
-  exposeStack(exposeStack = true) {
-    (0, import_props.solid)(this, "_exposeStack", !!exposeStack, false, true);
+  rise(code) {
+    if (code == null) {
+      return this;
+    }
+    this.code = code;
     return this;
   }
   toJSON() {
-    const { message, stack, _exposeStack } = this;
+    const { message, cause } = this;
     const body = { message, ...this };
-    if (_exposeStack) {
-      body.stack = stack;
-    } else {
-      delete body.stack;
+    if (cause) {
+      const { message: message2, stack } = cause;
+      body.cause = { message: message2, stack };
     }
     return body;
   }
@@ -104,8 +95,47 @@ var ApiError = class _ApiError extends Error {
   }
 };
 
+// src/arc/class/HttpError.js
+var import_props2 = require("@randajan/props");
+var HttpError = class _HttpError extends FetchError {
+  static is(any) {
+    return any && any instanceof _HttpError;
+  }
+  static code(code, message, httpStatusCode = 400, opt = {}) {
+    opt.code = code;
+    return new _HttpError(message, httpStatusCode, opt);
+  }
+  constructor(message, httpStatusCode = 400, options = {}) {
+    const { detail, exposeCause, ...opt } = options || {};
+    const http = httpStatusCode ?? 400;
+    const msg = message || `HTTP:${http}`;
+    super(msg, opt);
+    (0, import_props2.safe)(this, {}, "_exposeCause", (t) => !!t, void 0, false);
+    this.detail = detail;
+    this.httpStatusCode = http;
+    this._exposeCause = exposeCause;
+  }
+  exposeCause(exposeCause = true) {
+    this._exposeCause = exposeCause;
+    return this;
+  }
+  toJSON() {
+    const { message, cause, _exposeCause } = this;
+    const body = { message, ...this };
+    if (_exposeCause && cause) {
+      const { message: message2, stack } = cause;
+      body.cause = { message: message2, stack, ...cause };
+    }
+    return body;
+  }
+  toString() {
+    const { httpStatusCode } = this;
+    return super.toString() + ` [${httpStatusCode}]`;
+  }
+};
+
 // src/server/class/Api.js
-var import_props3 = require("@randajan/props");
+var import_props4 = require("@randajan/props");
 
 // src/arc/class/Functionable.js
 var Functionable = class extends Function {
@@ -137,10 +167,10 @@ var lockObject = (o) => {
 var info = lockObject(define_slib_info_default);
 var info_default = info;
 
-// src/arc/main.js
-var import_props2 = require("@randajan/props");
+// src/arc/opt.js
+var import_props3 = require("@randajan/props");
 var start = (opt) => {
-  if (opt.timestamp) {
+  if (opt.timetrack) {
     return opt.startAt = Date.now();
   }
 };
@@ -159,7 +189,7 @@ var endTime = (body, startAt) => {
     time.netIn = body.time.startAt - startAt;
     time.netOut = endAt - body.time.endAt;
   }
-  body.time = (0, import_props2.solids)({}, time);
+  body.time = (0, import_props3.solids)({}, time);
 };
 var end = (body, opt) => {
   const hasError = !!body.error;
@@ -172,29 +202,23 @@ var end = (body, opt) => {
     if (isFn(opt.onError)) {
       opt.onError(body, opt);
     }
-    if (opt.throwError || opt.resultOnly) {
+    if (opt.throwError) {
       throw body.error;
     }
   }
-  return opt.resultOnly ? body.result : Object.freeze(body);
+  return Object.freeze(body);
 };
-var diffVersion = (version) => {
-  const v1 = toStr(info.version);
-  const v2 = toStr(version);
-  if (v1 === v2) {
-    return;
-  }
-  const f1 = v1.split(".");
-  const f2 = v2.split(".");
-  if (f1[0] !== f2[0]) {
-    return "major";
-  }
-  if (f1[1] !== f2[1]) {
-    return "minor";
+var createTrait = (trait) => {
+  if (!trait) {
+    return (opt) => opt;
   }
-  if (f1[2] !== f2[2]) {
-    return "patch";
+  if (isFn(trait)) {
+    return trait;
   }
+  throw new Error("config.trait should be a function");
+};
+var configTrait = (config) => {
+  config.trait = createTrait(config.trait);
 };
 
 // src/server/tool.js
@@ -221,15 +245,32 @@ var tryFn = (any) => {
   }
   return r.result.then(wrapResult).catch(wrapError);
 };
+var normalizeServerError = (any, opt) => {
+  let err = any;
+  if (!HttpError.is(err)) {
+    let custom = isFn(opt.normalizeError);
+    if (custom) {
+      try {
+        err = opt.normalizeError(err, opt);
+      } catch {
+        custom = false;
+      }
+    }
+    if (!custom || !HttpError.is(err)) {
+      err = HttpError.code(0, "Unknown", 500, { cause: any });
+    }
+  }
+  return err.rise(1).rise(opt.code);
+};
 
 // src/server/class/static.js
 var apiExit = (resp, opt) => {
-  const { exposeStack } = opt;
+  const { exposeCause } = opt;
   resp.statusCode = 200;
   if (resp.error) {
-    resp.error = ApiError.to(0, resp.error, 500).rise(1).rise(opt.code);
+    resp.error = normalizeServerError(resp.error, opt);
     resp.statusCode = resp.error.httpStatusCode;
-    resp.error.exposeStack(!!exposeStack);
+    resp.error.exposeCause(!!exposeCause);
   }
   resp[info_default.name] = info_default.version;
   return end(resp, opt);
@@ -248,20 +289,6 @@ var apiResolve = (exe, opt) => {
   return resp.then((resp2) => apiExit(resp2, opt));
 };
 
-// src/arc/opt.js
-var createTrait = (trait) => {
-  if (!trait) {
-    return (opt) => opt;
-  }
-  if (isFn(trait)) {
-    return trait;
-  }
-  throw new Error("config.trait should be a function");
-};
-var configTrait = (config) => {
-  config.trait = createTrait(config.trait);
-};
-
 // src/server/class/Api.js
 var Api = class _Api extends Functionable {
   static create(config = {}) {
@@ -271,7 +298,7 @@ var Api = class _Api extends Functionable {
     configTrait(config);
     super((exe, opt) => apiResolve(exe, mrgObj(config, opt)));
     Object.freeze(config);
-    (0, import_props3.solid)(this, "config", config);
+    (0, import_props4.solid)(this, "config", config);
   }
   code(code, exe, opt = {}) {
     opt.code = code;
@@ -287,25 +314,7 @@ var createApi = Api.create;
 var server_default = createApi;
 
 // src/client/class/static.js
-var import_props4 = require("@randajan/props");
-
-// src/arc/url.js
-var _regexp = /^https?:\/\//i;
-var buildUrl = (inputUrl, params) => {
-  if (!params) {
-    return inputUrl;
-  }
-  const hasHost = _regexp.test(inputUrl);
-  const url = new URL(inputUrl, hasHost ? void 0 : "http://thisisonlyplaceholder.xyz");
-  url.hash = "";
-  for (const [key, value] of Object.entries(params)) {
-    if (value != null) {
-      url.searchParams.append(key, value);
-    }
-  }
-  ;
-  return hasHost ? url.toString() : url.pathname + url.search;
-};
+var import_props5 = require("@randajan/props");
 
 // src/arc/types/kinds/json.js
 var json_exports = {};
@@ -330,175 +339,222 @@ var decode2 = (body) => Object.fromEntries(new URLSearchParams(body));
 var encode2 = (body) => new URLSearchParams(body);
 
 // src/arc/types/index.js
-var types = { json: json_exports, form: form_exports };
-var getType = (typeName) => {
-  if (!typeName) {
+var _types = { json: json_exports, form: form_exports };
+var joinTypeNames = (types = {}) => {
+  const native = Object.keys(_types);
+  const custom = typeof types === "object" ? Object.keys(types) : [];
+  return `'${[.../* @__PURE__ */ new Set([...native, ...custom])].join("', '")}'`;
+};
+var getType = (propertyName, reqFnName, opt) => {
+  const tn = opt[propertyName] || opt.type;
+  if (!tn) {
     return json_exports;
   }
-  const type = types[typeName];
-  if (type) {
+  const customType = opt.types?.[tn];
+  const type = customType || _types[tn];
+  if (!type) {
+    throw new Error(`Unknown config.${propertyName} '${tn}'. Must be one of: ${joinTypeNames(opt.types)}`);
+  }
+  if (!customType) {
     return type;
   }
-  throw new Error(`Unknow config.type '${typeName}'. Must be one of: '${[...Object.keys(types)].join("', '")}'`);
+  if (!type.mime || typeof type.mime !== "string") {
+    throw new Error(`Type definition '${tn}' requires 'mime' to be a string`);
+  }
+  if (!isFn(type[reqFnName])) {
+    throw new Error(`Type definition '${tn}' requires '${reqFnName}' to be a function`);
+  }
+  return type;
 };
 var encodeBody = (opt) => {
-  const type = getType(opt.requestType || opt.type);
+  const type = getType("requestType", "encode", opt);
   opt.headers["Content-Type"] = type.mime;
   opt.body = type.encode(opt.body);
 };
 var attachBodyDecoder = (opt) => {
-  const type = getType(opt.responseType || opt.type);
+  const type = getType("responseType", "decode", opt);
   opt.headers["Accept"] = type.mime;
   opt.decodeBody = type.decode;
 };
 
-// src/client/class/static.js
-var prepareOpt = (url, opt, method) => {
-  start(opt);
-  opt.url = buildUrl(mrgStr(opt.url, url), opt.query);
-  if (method) {
-    opt.method = method;
+// src/client/url.js
+var _regexp = /^https?:\/\//i;
+var buildUrl = (inputUrl, params) => {
+  if (!params) {
+    return inputUrl;
   }
-  if (opt.body) {
-    encodeBody(opt);
+  const hasHost = _regexp.test(inputUrl);
+  const url = new URL(inputUrl, hasHost ? void 0 : "http://thisisonlyplaceholder.xyz");
+  url.hash = "";
+  for (const [key, value] of Object.entries(params)) {
+    if (value != null) {
+      url.searchParams.append(key, value);
+    }
   }
-  attachBodyDecoder(opt);
-  const hasTimeout = opt.timeout > 0;
-  if (opt.abortable || hasTimeout) {
-    opt.abortController = new AbortController();
-    opt.signal = opt.abortController.signal;
+  ;
+  return hasHost ? url.toString() : url.pathname + url.search;
+};
+
+// src/client/tool.js
+var diffVersion = (version) => {
+  const v1 = toStr(info.version);
+  const v2 = toStr(version);
+  if (v1 === v2) {
+    return;
   }
-  if (hasTimeout) {
-    opt.timeoutId = setTimeout(() => opt.abortController?.abort(ApiError.create(1, "Timeout", 408)), opt.timeout);
+  const f1 = v1.split(".");
+  const f2 = v2.split(".");
+  if (f1[0] !== f2[0]) {
+    return "major";
   }
-  if (isFn(opt.trait)) {
-    opt = opt.trait(opt) || opt;
+  if (f1[1] !== f2[1]) {
+    return "minor";
+  }
+  if (f1[2] !== f2[2]) {
+    return "patch";
   }
-  return opt;
 };
-var localReject = (opt, error) => {
-  const { httpStatusCode } = error;
-  error.rise(0).rise(opt.code || 0);
-  return end({ isOk: false, isRemote: false, isApiKit: false, statusCode: httpStatusCode, error }, opt);
+var failedError = (cause) => FetchError.code(1, "Failed", { cause });
+var timeoutError = (_) => FetchError.code(2, "Timeout");
+var abortError = (_) => FetchError.code(3, "Aborted");
+var statusError = (resp) => HttpError.code(4, resp.statusText, resp.status, { exposeCause: true });
+var unreadableError = (resp, cause) => resp.ok ? FetchError.code(5, "Unreadable", { cause }) : statusError(resp);
+var undecodableError = (resp, cause, detail) => resp.ok ? FetchError.code(6, "Undecodable", { cause, detail }) : statusError(resp);
+var parseHeaders = (resp, opt) => {
+  if (!resp || !opt.parseHeaders) {
+    return;
+  }
+  return Object.freeze(Object.fromEntries(resp.headers.entries()));
 };
-var statusError = ({ status, statusText }) => ApiError.create(4, statusText || status, status);
-var unreadableError = (resp) => resp.ok ? ApiError.create(3, "Unreadable", 415) : statusError(resp);
-var foreignError = (resp) => ({ isApiKit: false, error: statusError(resp) });
 var readText = async (resp) => {
   try {
     return await resp.text();
-  } catch {
-    throw unreadableError(resp);
+  } catch (err) {
+    throw unreadableError(resp, err);
   }
 };
-var decodeText = (text, opt, resp) => {
+var decodeText = (resp, opt, text) => {
   try {
     return opt.decodeBody(text);
-  } catch {
-    throw unreadableError(resp);
+  } catch (err) {
+    throw undecodableError(resp, err, text);
+  }
+};
+var normalizeClientError = (any, opt) => {
+  let err = any;
+  if (!FetchError.is(err)) {
+    let custom = isFn(opt.normalizeError);
+    if (custom) {
+      try {
+        err = opt.normalizeError(err, opt);
+      } catch {
+        custom = false;
+      }
+    }
+    if (!custom || !FetchError.is(err)) {
+      err = FetchError.code(0, "Unknown", { cause: any });
+    }
   }
+  return err.rise(0).rise(0);
 };
-var resolveEmpty = (resp) => {
-  if (!resp.ok && resp.status !== 304) {
-    return foreignError(resp);
+var reconstructApiError = (remoteErr) => {
+  if (!remoteErr) {
+    return;
   }
-  return { result: null, isApiKit: false };
+  const { message, code, httpStatusCode, cause, detail } = remoteErr;
+  return HttpError.code(code, message, httpStatusCode, { cause, detail, exposeCause: true });
+};
+var mrgOpt = (a, b) => {
+  const opt = mrgObj(a, b);
+  opt.body = mrgObj(a?.body, b?.body);
+  opt.params = mrgObj(a?.params, b?.params);
+  opt.headers = mrgObj(a?.headers, b?.headers, {});
+  return opt;
 };
-var resolveApiKit = (raw, opt) => {
-  const apv = raw[info_default.name];
-  const diff = diffVersion(apv);
-  const msg = `Detected @randajan/api-kit ${diff} version difference at '${opt.url}'. Server '${apv}' vs. client '${info_default.version}'`;
-  if (diff === "major") {
-    console.error(msg);
+var prepareOpt = (url, opt, method) => {
+  start(opt);
+  opt.url = buildUrl(mrgStr(opt.url, url), opt.params);
+  if (method) {
+    opt.method = method;
   }
-  if (diff === "minor") {
-    console.warn(msg);
+  if (opt.body) {
+    encodeBody(opt);
   }
-  raw.isApiKit = true;
-  return raw;
-};
-var resolveForeign = (raw, opt, resp) => {
-  if (!resp.ok) {
-    return foreignError(resp);
+  attachBodyDecoder(opt);
+  const hasTimeout = opt.timeout > 0;
+  if (opt.isAbortable || hasTimeout) {
+    opt.abortController = new AbortController();
+    opt.signal = opt.abortController.signal;
   }
-  const body = { isApiKit: false };
-  try {
-    body.result = opt.parseBody(raw);
-  } catch (err) {
-    body.error = err.message || err;
+  if (hasTimeout) {
+    opt.timeoutId = setTimeout(() => opt.abortController?.abort(timeoutError()), opt.timeout);
   }
-  return body;
-};
-var resolveDecoded = (raw, opt, resp) => {
-  if (raw?.[info_default.name]) {
-    return resolveApiKit(raw, opt);
+  if (isFn(opt.trait)) {
+    opt = opt.trait(opt) || opt;
   }
-  return resolveForeign(raw, opt, resp);
+  return opt;
 };
-var normalizeError = (body, opt, resp) => {
-  if (!body.error || ApiError.is(body.error)) {
-    return;
+
+// src/client/class/static.js
+var localReject = (err, opt) => ({ error: normalizeClientError(FetchError.is(err) ? err : failedError(err), opt) });
+var remoteReject = (err, opt) => ({ isRemote: true, error: normalizeClientError(err, opt) });
+var remoteResolve = async (resp, opt) => {
+  const text = await readText(resp);
+  if (!text) {
+    if (resp.ok || resp.status === 304) {
+      return { isRemote: true };
+    }
+    throw statusError(resp);
   }
-  const { code, message, stack, httpStatusCode } = body.error;
-  body.error = ApiError.create(
-    code || mrgStr(opt.code || 0, "1.0", "."),
-    message || body.error,
-    httpStatusCode ?? body.statusCode ?? resp.status,
-    stack
-  );
-};
-var remoteResolve = (body, opt, resp) => {
-  normalizeError(body, opt, resp);
-  body.isOk = !body.error;
-  body.isRemote = true;
-  body.isApiKit = !!body.isApiKit;
-  body.statusCode = body.statusCode ?? body.error?.httpStatusCode ?? resp.status;
-  if (opt.parseHeaders) {
-    body.headers = Object.freeze(Object.fromEntries(resp.headers.entries()));
+  const body = decodeText(resp, opt, text);
+  const ver = body?.[info_default.name];
+  if (!ver) {
+    if (resp.ok) {
+      return { isRemote: true, result: body };
+    }
+    throw statusError(resp);
   }
-  return end(body, opt);
+  body.isRemote = true;
+  body.isApiKit = true;
+  body.apiKitDiff = diffVersion(ver);
+  body.error = reconstructApiError(body.error);
+  return body;
 };
-var remoteReject = (opt, resp, error) => remoteResolve({ isApiKit: false, error }, opt, resp);
-var fetchExe = async (_fetch, opt) => {
+var fetchBody = async (_fetch, opt) => {
   let resp, body;
   try {
     resp = await _fetch(opt.url, opt);
-  } catch (err) {
-    return localReject(opt, ApiError.is(err) ? err : ApiError.to(0, "Failed", 503));
+  } catch (err2) {
+    body = localReject(err2, opt);
   }
   try {
-    const text = await readText(resp);
-    body = text ? resolveDecoded(decodeText(text, opt, resp), opt, resp) : resolveEmpty(resp);
-  } catch (err) {
-    return remoteReject(opt, resp, ApiError.is(err) ? err : ApiError.to(0, err, 500));
+    body = body || await remoteResolve(resp, opt);
+  } catch (err2) {
+    body = remoteReject(err2, opt);
   }
-  return remoteResolve(body, opt, resp);
-};
-var fetchResolve = (_fetch, url, opt, method) => {
-  const prom = fetchExe(_fetch, prepareOpt(url, opt, method));
+  const err = body.error;
+  body.isOk = !err;
+  body.isRemote = !!body.isRemote;
+  body.isApiKit = !!body.isApiKit;
+  body.statusCode = err?.httpStatusCode || resp?.status;
+  body.headers = parseHeaders(resp, opt);
+  body = end(body, opt);
+  return opt.resultOnly ? body.result : body;
+};
+var executeFetch = (_fetch, url, opt, method) => {
+  opt = prepareOpt(url, opt, method);
+  const prom = fetchBody(_fetch, opt);
   if (opt.timeoutId) {
     prom.finally((_) => clearTimeout(opt.timeoutId));
   }
-  if (!opt.abortable) {
+  if (!opt.isAbortable) {
     return prom;
   }
-  return (0, import_props4.solid)(prom, "abort", (_) => opt.abortController?.abort(ApiError.create(2, "Aborted", 499)));
-};
-
-// src/client/class/Fetch.js
-var import_props5 = require("@randajan/props");
-
-// src/client/tool.js
-var mrgQuery = (opt) => mrgObj(opt?.params, opt?.query);
-var mrgOpt = (a, b) => {
-  const opt = mrgObj(a, b);
-  opt.body = mrgObj(a?.body, b?.body);
-  opt.query = mrgObj(mrgQuery(a), mrgQuery(b));
-  opt.headers = mrgObj(a?.headers, b?.headers, {});
-  return opt;
+  return (0, import_props5.solid)(prom, "abort", (_) => opt.abortController?.abort(abortError()));
 };
 
 // src/client/class/Fetch.js
+var import_props6 = require("@randajan/props");
 var Fetch = class _Fetch extends Functionable {
   static create(config = {}) {
     return new _Fetch(config);
@@ -506,14 +562,13 @@ var Fetch = class _Fetch extends Functionable {
   constructor(config = {}) {
     const _fetch = config.fetch || globalThis.fetch;
     if (!_fetch) {
-      throw new Error("Missing fetch function. Please provide it inconfig");
+      throw new Error("Missing fetch function. Please provide it in config");
     }
     configTrait(config);
-    config.parseBody = createTrait(config.parseBody);
     delete config.fetch;
-    super((url, opt, method) => fetchResolve(_fetch, url, mrgOpt(config, opt), method));
+    super((url, opt, method) => executeFetch(_fetch, url, mrgOpt(config, opt), method));
     Object.freeze(config);
-    (0, import_props5.solid)(this, "config", config);
+    (0, import_props6.solid)(this, "config", config);
   }
   extend(config) {
     return new _Fetch(mrgOpt(this.config, config));