@ptx-showcase/utils 0.3.0 → 0.4.0

package/README.md

@@ -58,13 +58,13 @@ import { buildSortParam } from '@ptx-showcase/utils'
 // from subpath
 import { buildSortParam } from '@ptx-showcase/utils/build-sort-param'
 
-buildSortParam('name')              // → 'name'
-buildSortParam('name', 'name')      // → '-name'
-buildSortParam('name', '-name')     // → ''
+buildSortParam('name') // → 'name'
+buildSortParam('name', 'name') // → '-name'
+buildSortParam('name', '-name') // → ''
 
 // combining with existing sort
-buildSortParam('age', 'name')       // → 'age,name'
-buildSortParam('age', 'age,name')   // → '-age,name'
+buildSortParam('age', 'name') // → 'age,name'
+buildSortParam('age', 'age,name') // → '-age,name'
 ```
 
 ---
@@ -96,7 +96,7 @@ deleteCookie('token')
 Default options:
 
 | Option     | Value      |
-|------------|------------|
+| ---------- | ---------- |
 | `expires`  | 1 hour     |
 | `secure`   | `true`     |
 | `sameSite` | `'Strict'` |
@@ -126,16 +126,50 @@ await downloadBlob(blob, { hash: 12345 })
 
 ---
 
+### handleApiError
+
+Parses backend error responses (including `ky`'s `HTTPError`) and reports human-readable messages through whatever notification system your project uses (`vue-sonner`, `react-hot-toast`, `console.error`, etc).
+
+The utility is UI-agnostic: call `initHandleApiError` once at app startup with a `notify` function, then call `handleApiError` from anywhere without touching the notification library again. Without initialization, messages fall back to `console.error`.
+
+```ts
+// from root
+import { handleApiError, initHandleApiError } from '@ptx-showcase/utils'
+
+// from subpath
+import { handleApiError, initHandleApiError } from '@ptx-showcase/utils/handle-api-error'
+
+// Vue project (e.g. main.ts), using vue-sonner
+import { toast } from 'vue-sonner'
+
+initHandleApiError({ notify: (message) => toast.error(message) })
+
+// React project (e.g. app entry), using react-hot-toast
+import toast from 'react-hot-toast'
+
+initHandleApiError({ notify: (message) => toast.error(message) })
+
+// anywhere in either project
+try {
+	await api.get('users')
+} catch (error) {
+	handleApiError(error)
+}
+```
+
+---
+
 ## Available modules
 
-| Subpath                                     | Exports                                              |
-|---------------------------------------------|------------------------------------------------------|
-| `@ptx-showcase/utils`                       | all utilities                                        |
-| `@ptx-showcase/utils/build-query-params`    | `buildQueryParams`                                   |
-| `@ptx-showcase/utils/build-sort-param`      | `buildSortParam`                                     |
-| `@ptx-showcase/utils/cookies`               | `setCookie`, `getCookie`, `deleteCookie`, `defaultCookieOptions` |
-| `@ptx-showcase/utils/download-file`         | `downloadBlob`                                       |
-| `@ptx-showcase/utils/types`                 | `TableColumnConfig`                                  |
+| Subpath                                  | Exports                                                          |
+| ---------------------------------------- | ---------------------------------------------------------------- |
+| `@ptx-showcase/utils`                    | all utilities                                                    |
+| `@ptx-showcase/utils/build-query-params` | `buildQueryParams`                                               |
+| `@ptx-showcase/utils/build-sort-param`   | `buildSortParam`                                                 |
+| `@ptx-showcase/utils/cookies`            | `setCookie`, `getCookie`, `deleteCookie`, `defaultCookieOptions` |
+| `@ptx-showcase/utils/download-file`      | `downloadBlob`                                                   |
+| `@ptx-showcase/utils/handle-api-error`   | `handleApiError`, `initHandleApiError`                           |
+| `@ptx-showcase/utils/types`              | `TableColumnConfig`, `PaginatedList`                             |
 
 ---
 

package/dist/build-query-params/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=e=>{let t=new URLSearchParams;Object.entries(e).forEach(([e,n])=>{n==null||n===``||Array.isArray(n)&&n.length===0||t.append(e,String(n))});let n=t.toString();return n?`?${n}`:``};exports.buildQueryParams=e;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=e=>{let t=new URLSearchParams;Object.entries(e).forEach(([e,n])=>{n!=null&&n!==``&&(Array.isArray(n)&&n.length===0||t.append(e,String(n)))});let n=t.toString();return n?`?${n}`:``};exports.buildQueryParams=e;

package/dist/build-query-params/index.js

@@ -2,7 +2,7 @@
 var e = (e) => {
 	let t = new URLSearchParams();
 	Object.entries(e).forEach(([e, n]) => {
-		n == null || n === "" || Array.isArray(n) && n.length === 0 || t.append(e, String(n));
+		n != null && n !== "" && (Array.isArray(n) && n.length === 0 || t.append(e, String(n)));
 	});
 	let n = t.toString();
 	return n ? `?${n}` : "";

package/dist/chunks/handle-api-error-CMd_LxPS.es

@@ -0,0 +1,38 @@
+import { isHTTPError as e } from "ky";
+//#region src/handle-api-error/constants/handle-api-error.constant.ts
+var t = "Something went wrong", n = /* @__PURE__ */ new Set([
+	"message",
+	"detail",
+	"error",
+	"msg"
+]), r = (e) => typeof e == "object" && !!e && !Array.isArray(e), i = (e) => typeof e == "string" && e.trim() ? e : null, a = (e, t) => typeof e == "string" ? e.trim() ? [t ? `${t}: ${e}` : e] : [] : Array.isArray(e) ? e.flatMap((e) => a(e, t)) : r(e) ? Object.entries(e).flatMap(([e, t]) => a(t, e === "non_field_errors" ? void 0 : e)) : [], o = (e) => {
+	if (!e) return [];
+	if (typeof e == "string") return [e];
+	if (Array.isArray(e)) return e.filter((e) => typeof e == "string" && !!e.trim());
+	let t = i(e.detail) ?? i(e.message) ?? i(e.error) ?? i(e.msg);
+	return [...Object.entries(e).flatMap(([e, t]) => n.has(e) ? [] : e === "non_field_errors" || e === "errors" ? a(t) : a(t, e)), ...t ? [t] : []];
+}, s = (e) => {
+	console.error(e);
+}, c = (e) => {
+	s = e;
+}, l = () => s, u = (e) => {
+	c(e.notify);
+}, d = (n) => {
+	let r = l();
+	if (e(n)) {
+		let e = n.data, i = [...new Set(o(e))];
+		if (i.length > 0) {
+			i.forEach((e) => r(e));
+			return;
+		}
+		r(t);
+		return;
+	}
+	if (n instanceof Error) {
+		r(n.message || "Something went wrong");
+		return;
+	}
+	r(t);
+};
+//#endregion
+export { u as n, d as t };

package/dist/chunks/handle-api-error-D714W9rp.cjs

@@ -0,0 +1 @@
+let e=require("ky");var t=`Something went wrong`,n=new Set([`message`,`detail`,`error`,`msg`]),r=e=>typeof e==`object`&&!!e&&!Array.isArray(e),i=e=>typeof e==`string`&&e.trim()?e:null,a=(e,t)=>typeof e==`string`?e.trim()?[t?`${t}: ${e}`:e]:[]:Array.isArray(e)?e.flatMap(e=>a(e,t)):r(e)?Object.entries(e).flatMap(([e,t])=>a(t,e===`non_field_errors`?void 0:e)):[],o=e=>{if(!e)return[];if(typeof e==`string`)return[e];if(Array.isArray(e))return e.filter(e=>typeof e==`string`&&!!e.trim());let t=i(e.detail)??i(e.message)??i(e.error)??i(e.msg);return[...Object.entries(e).flatMap(([e,t])=>n.has(e)?[]:e===`non_field_errors`||e===`errors`?a(t):a(t,e)),...t?[t]:[]]},s=e=>{console.error(e)},c=e=>{s=e},l=()=>s,u=e=>{c(e.notify)},d=n=>{let r=l();if((0,e.isHTTPError)(n)){let e=n.data,i=[...new Set(o(e))];if(i.length>0){i.forEach(e=>r(e));return}r(t);return}if(n instanceof Error){r(n.message||`Something went wrong`);return}r(t)};Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return u}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return d}});

package/dist/cookies/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../chunks/cookies-BayERMbH.cjs");exports.defaultCookieOptions=e.t,exports.deleteCookie=e.n,exports.getCookie=e.r,exports.setCookie=e.i;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,s)=>(s=n==null?{}:e(i(n)),o(r||!n||!n.__esModule||!a.call(n,`default`)?t(s,`default`,{value:n,enumerable:!0}):s,n));let c=require("js-cookie");c=s(c,1);var l={expires:1/24,secure:!0,sameSite:`Strict`},u=(e,t,n)=>{c.default.set(e,t,{...l,...n})},d=e=>c.default.get(e),f=(e,t)=>{c.default.remove(e,t)};exports.defaultCookieOptions=l,exports.deleteCookie=f,exports.getCookie=d,exports.setCookie=u;

package/dist/download-file/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("file-saver");var t=async e=>{let t=new TextEncoder().encode(String(e)),n=await crypto.subtle.digest(`SHA-1`,t);return Array.from(new Uint8Array(n)).map(e=>e.toString(16).padStart(2,`0`)).join(``)},n=async(n,r)=>{if(!(n instanceof Blob))throw Error(`downloadBlob: expected Blob, got ${typeof n}`);(0,e.saveAs)(n,`filename`in r?r.filename:await t(r.hash))};exports.downloadBlob=n;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("file-saver");var t=async e=>{let t=new TextEncoder().encode(String(e)),n=await crypto.subtle.digest(`SHA-1`,t);return Array.from(new Uint8Array(n)).map(e=>e.toString(16).padStart(2,`0`)).join(``)},n=async(n,r)=>{if(!(n instanceof Blob))throw Error(`downloadBlob: expected Blob, got ${typeof n}`);let i=`filename`in r?r.filename:await t(r.hash);(0,e.saveAs)(n,i)};exports.downloadBlob=n;

package/dist/download-file/index.js

@@ -5,7 +5,8 @@ var t = async (e) => {
 	return Array.from(new Uint8Array(n)).map((e) => e.toString(16).padStart(2, "0")).join("");
 }, n = async (n, r) => {
 	if (!(n instanceof Blob)) throw Error(`downloadBlob: expected Blob, got ${typeof n}`);
-	e(n, "filename" in r ? r.filename : await t(r.hash));
+	let i = "filename" in r ? r.filename : await t(r.hash);
+	e(n, i);
 };
 //#endregion
 export { n as downloadBlob };

package/dist/handle-api-error/constants/handle-api-error.constant.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_ERROR_MESSAGE: "Something went wrong";
+export declare const SKIPPED_KEYS: Set<string>;

package/dist/handle-api-error/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../chunks/handle-api-error-D714W9rp.cjs");exports.handleApiError=e.t,exports.initHandleApiError=e.n;

package/dist/handle-api-error/index.d.ts

@@ -0,0 +1,3 @@
+import { HandleApiErrorConfig } from './types/handle-api-error.type';
+export declare const initHandleApiError: (config: HandleApiErrorConfig) => void;
+export declare const handleApiError: (error: unknown) => void;

package/dist/handle-api-error/index.js

@@ -0,0 +1,2 @@
+import { n as e, t } from "../chunks/handle-api-error-CMd_LxPS.es";
+export { t as handleApiError, e as initHandleApiError };

package/dist/handle-api-error/libs/handle-api-error.lib.d.ts

@@ -0,0 +1,5 @@
+import { ApiErrorData, ApiErrorPrimitive } from '../types/handle-api-error.type';
+export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+export declare const toMessage: (value: unknown) => string | null;
+export declare const extractMessages: (value: unknown, parentKey?: string) => string[];
+export declare const getHttpErrorMessages: (errorData: ApiErrorData | ApiErrorPrimitive | undefined) => string[];

package/dist/handle-api-error/libs/init-handle-api-error.lib.d.ts

@@ -0,0 +1,3 @@
+import { NotifyFn } from '../types/handle-api-error.type';
+export declare const setNotify: (fn: NotifyFn) => void;
+export declare const getNotify: () => NotifyFn;

package/dist/handle-api-error/types/handle-api-error.type.d.ts

@@ -0,0 +1,14 @@
+export type NotifyFn = (message: string) => void;
+export interface HandleApiErrorConfig {
+    notify: NotifyFn;
+}
+export type ApiErrorPrimitive = string | string[];
+export interface ApiErrorData {
+    detail?: string;
+    message?: string;
+    error?: string;
+    msg?: string;
+    non_field_errors?: string[];
+    errors?: unknown;
+    [key: string]: unknown;
+}

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./chunks/cookies-BayERMbH.cjs"),t=require("./build-query-params/index.cjs"),n=require("./clean-object/index.cjs"),r=require("./build-sort-param/index.cjs"),i=require("./download-file/index.cjs"),a=require("./normalize-input/index.cjs");exports.buildQueryParams=t.buildQueryParams,exports.buildSortParam=r.buildSortParam,exports.cleanObject=n.cleanObject,exports.defaultCookieOptions=e.t,exports.deleteCookie=e.n,exports.downloadBlob=i.downloadBlob,exports.getCookie=e.r,exports.normalizeDecimalInput=a.normalizeDecimalInput,exports.normalizePhoneNumberInput=a.normalizePhoneNumberInput,exports.setCookie=e.i;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./build-query-params/index.cjs"),t=require("./clean-object/index.cjs"),n=require("./cookies/index.cjs"),r=require("./build-sort-param/index.cjs"),i=require("./download-file/index.cjs"),a=require("./chunks/handle-api-error-D714W9rp.cjs"),o=require("./normalize-input/index.cjs");exports.buildQueryParams=e.buildQueryParams,exports.buildSortParam=r.buildSortParam,exports.cleanObject=t.cleanObject,exports.defaultCookieOptions=n.defaultCookieOptions,exports.deleteCookie=n.deleteCookie,exports.downloadBlob=i.downloadBlob,exports.getCookie=n.getCookie,exports.handleApiError=a.t,exports.initHandleApiError=a.n,exports.normalizeDecimalInput=o.normalizeDecimalInput,exports.normalizePhoneNumberInput=o.normalizePhoneNumberInput,exports.setCookie=n.setCookie;

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export * from './cookies';
 export type * from './types';
 export * from './build-sort-param';
 export * from './download-file';
+export * from './handle-api-error';
 export * from './normalize-input';

package/dist/index.js

@@ -3,5 +3,6 @@ import { cleanObject as t } from "./clean-object/index.js";
 import { defaultCookieOptions as n, deleteCookie as r, getCookie as i, setCookie as a } from "./cookies/index.js";
 import { buildSortParam as o } from "./build-sort-param/index.js";
 import { downloadBlob as s } from "./download-file/index.js";
-import { normalizeDecimalInput as c, normalizePhoneNumberInput as l } from "./normalize-input/index.js";
-export { e as buildQueryParams, o as buildSortParam, t as cleanObject, n as defaultCookieOptions, r as deleteCookie, s as downloadBlob, i as getCookie, c as normalizeDecimalInput, l as normalizePhoneNumberInput, a as setCookie };
+import { n as c, t as l } from "./chunks/handle-api-error-CMd_LxPS.es";
+import { normalizeDecimalInput as u, normalizePhoneNumberInput as d } from "./normalize-input/index.js";
+export { e as buildQueryParams, o as buildSortParam, t as cleanObject, n as defaultCookieOptions, r as deleteCookie, s as downloadBlob, i as getCookie, l as handleApiError, c as initHandleApiError, u as normalizeDecimalInput, d as normalizePhoneNumberInput, a as setCookie };

package/dist/types/index.d.ts

@@ -4,3 +4,10 @@ export interface TableColumnConfig<T, ExtraKeys extends string = never> {
     key: keyof T | ExtraKeys;
     sortable?: boolean;
 }
+export interface PaginatedList<T> {
+    items: T[];
+    page: number;
+    per_page: number;
+    total_items: number;
+    total_pages: number;
+}

package/package.json

@@ -2,13 +2,13 @@
 	"name": "@ptx-showcase/utils",
 	"author": "ptx-showcase",
 	"description": "Shared utilities for PTX Showcase projects",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"private": false,
 	"type": "module",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/gibPerviy/ptx-showcase-utils"
+		"url": "git+https://github.com/gibPerviy/ptx-showcase-utils.git"
 	},
 	"homepage": "https://github.com/gibPerviy/ptx-showcase-utils#readme",
 	"bugs": {
@@ -56,6 +56,11 @@
 			"require": "./dist/download-file/index.cjs",
 			"types": "./dist/download-file/index.d.ts"
 		},
+		"./handle-api-error": {
+			"import": "./dist/handle-api-error/index.js",
+			"require": "./dist/handle-api-error/index.cjs",
+			"types": "./dist/handle-api-error/index.d.ts"
+		},
 		"./normalize-input": {
 			"import": "./dist/normalize-input/index.js",
 			"require": "./dist/normalize-input/index.cjs",
@@ -71,24 +76,31 @@
 		"dev": "vite",
 		"test": "vitest",
 		"build": "vite build",
+		"lint": "oxlint",
+		"lint:fix": "oxlint --fix",
+		"fmt": "oxfmt",
+		"fmt:check": "oxfmt --check",
+		"pre:commit": "oxfmt && oxlint && vite build",
 		"release": "bumpp"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
 	"devDependencies": {
-		"@types/node": "^25.9.2",
-		"bumpp": "^11.1.0",
-		"oxlint": "^1.68.0",
+		"@types/node": "^26.1.2",
+		"bumpp": "^12.2.0",
+		"oxfmt": "^0.62.0",
+		"oxlint": "^1.77.0",
 		"typescript": "~6.0.3",
-		"vite": "^8.0.16",
-		"vite-plugin-dts": "^5.0.2",
-		"vitest": "^4.1.8"
+		"vite": "^8.2.1",
+		"vite-plugin-dts": "^5.0.3",
+		"vitest": "^4.1.10"
 	},
 	"dependencies": {
 		"@types/file-saver": "^2.0.7",
 		"@types/js-cookie": "^3.0.6",
 		"file-saver": "^2.0.5",
-		"js-cookie": "^3.0.8"
+		"js-cookie": "^3.0.8",
+		"ky": "^2.0.2"
 	}
 }

package/dist/chunks/cookies-BayERMbH.cjs

@@ -1 +0,0 @@
-var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let c=require("js-cookie");c=s(c,1);var l={expires:1/24,secure:!0,sameSite:`Strict`},u=(e,t,n)=>{c.default.set(e,t,{...l,...n})},d=e=>c.default.get(e),f=(e,t)=>{c.default.remove(e,t)};Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return u}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return f}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return d}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return l}});