@randajan/api-kit 1.2.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.1.1", 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,34 +58,36 @@ 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) {
-    return new _ApiError(code, message);
-  }
+// 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) {
-    if (_ApiError.is(any)) {
-      return any;
-    }
-    const msg = toStr(any?.message || any) || "Unknown";
-    const apierr = _ApiError.create(code, msg);
-    return (0, import_props.solid)(apierr, "stack", any.stack, false);
+  static code(code, message, opt = {}) {
+    opt.code = code;
+    return new _FetchError(message, opt);
   }
-  constructor(code, message) {
-    super(message);
+  constructor(message, options = {}) {
+    const { code, ...opt } = options || {};
+    super(message, opt);
     (0, import_props.safe)(this, {}, "code", (t, f) => mrgStr(t, f, "."));
     this.rise(code);
   }
-  rise(code = 0) {
-    this.code = code || 0;
+  rise(code) {
+    if (code == null) {
+      return this;
+    }
+    this.code = code;
     return this;
   }
   toJSON() {
-    const { message } = this;
-    return { message, ...this };
+    const { message, cause } = this;
+    const body = { message, ...this };
+    if (cause) {
+      const { message: message2, stack } = cause;
+      body.cause = { message: message2, stack };
+    }
+    return body;
   }
   toString() {
     const { message, code } = this;
@@ -92,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 {
@@ -125,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();
   }
 };
@@ -147,10 +189,12 @@ 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) => {
-  if (!body.error) {
+  const hasError = !!body.error;
+  endTime(body, opt.startAt);
+  if (!hasError) {
     if (isFn(opt.onOk)) {
       opt.onOk(body, opt);
     }
@@ -162,26 +206,19 @@ var end = (body, opt) => {
       throw body.error;
     }
   }
-  endTime(body, opt.startAt);
-  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
@@ -208,11 +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 { exposeCause } = opt;
+  resp.statusCode = 200;
   if (resp.error) {
-    resp.error = ApiError.to(0, resp.error).rise(1).rise(opt.code);
+    resp.error = normalizeServerError(resp.error, opt);
+    resp.statusCode = resp.error.httpStatusCode;
+    resp.error.exposeCause(!!exposeCause);
   }
   resp[info_default.name] = info_default.version;
   return end(resp, opt);
@@ -231,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 = {}) {
@@ -254,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;
@@ -270,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 = {};
@@ -313,32 +339,141 @@ 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
+// src/client/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;
+};
+
+// src/client/tool.js
+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";
+  }
+  if (f1[2] !== f2[2]) {
+    return "patch";
+  }
+};
+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 readText = async (resp) => {
+  try {
+    return await resp.text();
+  } catch (err) {
+    throw unreadableError(resp, err);
+  }
+};
+var decodeText = (resp, opt, text) => {
+  try {
+    return opt.decodeBody(text);
+  } 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 reconstructApiError = (remoteErr) => {
+  if (!remoteErr) {
+    return;
+  }
+  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 prepareOpt = (url, opt, method) => {
   start(opt);
-  opt.url = buildUrl(mrgStr(opt.url, url), opt.query);
+  opt.url = buildUrl(mrgStr(opt.url, url), opt.params);
   if (method) {
     opt.method = method;
   }
@@ -347,101 +482,79 @@ var prepareOpt = (url, opt, method) => {
   }
   attachBodyDecoder(opt);
   const hasTimeout = opt.timeout > 0;
-  if (opt.abortable || hasTimeout) {
+  if (opt.isAbortable || hasTimeout) {
     opt.abortController = new AbortController();
     opt.signal = opt.abortController.signal;
   }
   if (hasTimeout) {
-    opt.timeoutId = setTimeout(() => opt.abortController?.abort(new ApiError(1, "Timeout")), opt.timeout);
+    opt.timeoutId = setTimeout(() => opt.abortController?.abort(timeoutError()), opt.timeout);
   }
   if (isFn(opt.trait)) {
     opt = opt.trait(opt) || opt;
   }
   return opt;
 };
-var localReject = (opt, error, http) => {
-  const { code } = error;
-  if (code == 0) {
-    http = 503;
-  } else if (code == 1) {
-    http = 408;
-  } else if (code == 2) {
-    http = 499;
-  } else if (code == 3) {
-    http = 415;
-  } else if (!http) {
-    http = 400;
-  }
-  error.rise(0).rise(opt.code || 0);
-  return end({ ok: false, http, error }, opt);
-};
-var fetchExe = async (_fetch, opt) => {
-  let resp, raw, body;
-  try {
-    resp = await _fetch(opt.url, opt);
-  } catch (err) {
-    return localReject(opt, ApiError.is(err) ? err : ApiError.to(0, "Failed"));
-  }
-  const { ok, status, headers, statusText } = resp;
-  try {
-    raw = opt.decodeBody(await resp.text());
-  } catch {
-    return localReject(opt, new ApiError(ok ? 3 : 4, ok ? "Unreadable" : statusText || status), status);
-  }
-  const apv = raw[info_default.name];
-  if (apv) {
-    body = raw;
-    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);
-    }
-    if (diff === "minor") {
-      console.warn(msg);
-    }
-  } else {
-    body = {};
-    try {
-      body.result = opt.parseBody(raw);
-    } catch (err) {
-      body.error = err.message || err;
+
+// 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);
   }
-  if (body.error) {
-    const { code, message } = body.error;
-    body.error = new ApiError(code || mrgStr(opt.code || 0, "1.0", "."), message || body.error);
+  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);
   }
-  body.ok = !body.error;
-  body.http = status;
-  if (opt.parseHeaders) {
-    body.headers = Object.freeze(Object.fromEntries(headers.entries()));
+  body.isRemote = true;
+  body.isApiKit = true;
+  body.apiKitDiff = diffVersion(ver);
+  body.error = reconstructApiError(body.error);
+  return body;
+};
+var fetchBody = async (_fetch, opt) => {
+  let resp, body;
+  try {
+    resp = await _fetch(opt.url, opt);
+  } catch (err2) {
+    body = localReject(err2, opt);
   }
-  return end(body, opt);
+  try {
+    body = body || await remoteResolve(resp, opt);
+  } catch (err2) {
+    body = remoteReject(err2, opt);
+  }
+  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 fetchResolve = (_fetch, url, opt, method) => {
-  const prom = fetchExe(_fetch, prepareOpt(url, opt, method));
+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(new ApiError(2, "Aborted")));
-};
-
-// src/client/class/Fetch.js
-var import_props5 = require("@randajan/props");
-
-// src/client/tool.js
-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;
+  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);
@@ -449,37 +562,36 @@ 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));
   }
-  async get(url, opt) {
+  get(url, opt) {
     return this(url, opt, "GET");
   }
-  async post(url, opt) {
+  post(url, opt) {
     return this(url, opt, "POST");
   }
-  async put(url, opt) {
+  put(url, opt) {
     return this(url, opt, "PUT");
   }
-  async delete(url, opt) {
+  delete(url, opt) {
     return this(url, opt, "DELETE");
   }
-  async patch(url, opt) {
+  patch(url, opt) {
     return this(url, opt, "PATCH");
   }
-  async head(url, opt) {
+  head(url, opt) {
     return this(url, opt, "HEAD");
   }
-  async options(url, opt) {
+  options(url, opt) {
     return this(url, opt, "OPTIONS");
   }
 };