@ptx-showcase/utils 0.2.2 → 0.2.4

package/README.md

@@ -4,7 +4,7 @@ Shared utilities for PTX Showcase projects.
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @ptx-showcase/utils
@@ -18,42 +18,128 @@ bun add @ptx-showcase/utils
 
 ---
 
-## 🚀 Usage
+## Usage
 
-### Cookie utilities
+All utilities can be imported from the root package or from a specific subpath.
+
+---
+
+### buildQueryParams
+
+Builds a URL query string from an object. Skips `null`, `undefined`, empty strings, and empty arrays.
+
+```ts
+// from root
+import { buildQueryParams } from '@ptx-showcase/utils'
+
+// from subpath
+import { buildQueryParams } from '@ptx-showcase/utils/build-query-params'
+
+buildQueryParams({ page: 1, search: 'test', empty: '' })
+// → '?page=1&search=test'
+
+buildQueryParams({ ids: [], status: 'active' })
+// → '?status=active'
+
+buildQueryParams({})
+// → ''
+```
+
+---
+
+### buildSortParam
+
+Builds a comma-separated sort string with toggle logic: first call adds the field, second toggles to descending (`-field`), third removes it.
+
+```ts
+// from root
+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')     // → ''
+
+// combining with existing sort
+buildSortParam('age', 'name')       // → 'age,name'
+buildSortParam('age', 'age,name')   // → '-age,name'
+```
+
+---
+
+### Cookies
+
+Cookie helpers with secure defaults (`expires: 1h`, `secure: true`, `sameSite: Strict`).
 
 ```ts
+// from root
+import { setCookie, getCookie, deleteCookie } from '@ptx-showcase/utils'
+
+// from subpath
 import { setCookie, getCookie, deleteCookie } from '@ptx-showcase/utils/cookies'
 
-// set cookie
-setCookie('token', '123')
+// set (uses default options)
+setCookie('token', 'abc123')
+
+// set with custom options
+setCookie('session', 'xyz', { expires: 7, sameSite: 'Lax' })
 
-// get cookie
-const token = getCookie('token')
+// get
+const token = getCookie('token') // → 'abc123' | undefined
 
-// delete cookie
+// delete
 deleteCookie('token')
 ```
 
+Default options:
+
+| Option     | Value      |
+|------------|------------|
+| `expires`  | 1 hour     |
+| `secure`   | `true`     |
+| `sameSite` | `'Strict'` |
+
 ---
 
-## 📁 Available modules
+### downloadBlob
+
+Downloads a `Blob` as a file in the browser. Accepts either an explicit filename or a hash value (auto-generates a SHA-1 filename).
+
+```ts
+// from root
+import { downloadBlob } from '@ptx-showcase/utils'
 
-- `@ptx-showcase/utils` — base utilities
-- `@ptx-showcase/utils/cookie` — cookie helpers
+// from subpath
+import { downloadBlob } from '@ptx-showcase/utils/download-file'
+
+const blob = new Blob(['Hello, World!'], { type: 'text/plain' })
+
+// with explicit filename
+await downloadBlob(blob, { filename: 'report.txt' })
+
+// with auto-generated SHA-1 filename
+await downloadBlob(blob, { hash: 12345 })
+// → saves as e.g. '17b840d9...'
+```
 
 ---
 
-## 🧠 Features
+## Available modules
 
-- TypeScript support out of the box
-- ESM + CommonJS compatibility
-- Modular architecture (subpath imports)
-- Lightweight and reusable across projects
+| 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`                                  |
 
 ---
 
-## 🔄 Versioning
+## Versioning
 
 This package follows [Semantic Versioning](https://semver.org/):
 
@@ -63,12 +149,12 @@ This package follows [Semantic Versioning](https://semver.org/):
 
 ---
 
-## 📜 Changelog
+## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md) for all changes.
 
 ---
 
-## 📄 License
+## License
 
 MIT

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===``||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 === "" || 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/download-file/index.cjs

@@ -0,0 +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;

package/dist/download-file/index.d.ts

@@ -0,0 +1,7 @@
+type DownloadBlobOptions = {
+    filename: string;
+} | {
+    hash: string | number;
+};
+export declare const downloadBlob: (blob: Blob, options: DownloadBlobOptions) => Promise<void>;
+export {};

package/dist/download-file/index.js

@@ -0,0 +1,11 @@
+import { saveAs as e } from "file-saver";
+//#region src/download-file/index.ts
+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}`);
+	e(n, "filename" in r ? r.filename : await t(r.hash));
+};
+//#endregion
+export { n as downloadBlob };

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");exports.buildQueryParams=t.buildQueryParams,exports.buildSortParam=r.buildSortParam,exports.cleanObject=n.cleanObject,exports.defaultCookieOptions=e.t,exports.deleteCookie=e.n,exports.getCookie=e.r,exports.setCookie=e.i;
+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");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.setCookie=e.i;

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export * from './clean-object';
 export * from './cookies';
 export type * from './types';
 export * from './build-sort-param';
+export * from './download-file';

package/dist/index.js

@@ -2,4 +2,5 @@ import { buildQueryParams as e } from "./build-query-params/index.js";
 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";
-export { e as buildQueryParams, o as buildSortParam, t as cleanObject, n as defaultCookieOptions, r as deleteCookie, i as getCookie, a as setCookie };
+import { downloadBlob as s } from "./download-file/index.js";
+export { e as buildQueryParams, o as buildSortParam, t as cleanObject, n as defaultCookieOptions, r as deleteCookie, s as downloadBlob, i as getCookie, a as setCookie };

package/package.json

@@ -2,7 +2,7 @@
 	"name": "@ptx-showcase/utils",
 	"author": "ptx-showcase",
 	"description": "Shared utilities for PTX Showcase projects",
-	"version": "0.2.2",
+	"version": "0.2.4",
 	"private": false,
 	"type": "module",
 	"license": "MIT",
@@ -51,6 +51,11 @@
 			"require": "./dist/clean-object/index.cjs",
 			"types": "./dist/clean-object/index.d.ts"
 		},
+		"./download-file": {
+			"import": "./dist/download-file/index.js",
+			"require": "./dist/download-file/index.cjs",
+			"types": "./dist/download-file/index.d.ts"
+		},
 		"./types": {
 			"import": "./dist/types/index.js",
 			"require": "./dist/types/index.cjs",
@@ -67,16 +72,18 @@
 		"access": "public"
 	},
 	"devDependencies": {
-		"@types/node": "^25.9.1",
+		"@types/node": "^25.9.2",
 		"bumpp": "^11.1.0",
-		"oxlint": "^1.67.0",
+		"oxlint": "^1.68.0",
 		"typescript": "~6.0.3",
-		"vite": "^8.0.14",
-		"vite-plugin-dts": "^5.0.1",
-		"vitest": "^4.1.7"
+		"vite": "^8.0.16",
+		"vite-plugin-dts": "^5.0.2",
+		"vitest": "^4.1.8"
 	},
 	"dependencies": {
+		"@types/file-saver": "^2.0.7",
 		"@types/js-cookie": "^3.0.6",
-		"js-cookie": "^3.0.7"
+		"file-saver": "^2.0.5",
+		"js-cookie": "^3.0.8"
 	}
 }