Updated cache

.gitmodules

@@ -2,4 +2,4 @@
 	path = docs
 	url = git@git.zakscode.com:ztimson/utils.wiki.git
 	branch = master
-	ignore = any
+	ignore = all

README.md

@@ -20,9 +20,10 @@ Javascript/Typescript Utilities
 
   ---
   <div>
-    <a href="https://git.zakscode.com/ztimson/persist/releases" target="_blank">Release Notes</a>
+    <a href="https://git.zakscode.com/ztimson/utils/wiki" target="_blank">Documentation</a>
-    • <a href="https://git.zakscode.com/ztimson/persist/issues/new?template=.github%2fissue_template%2fbug.md" target="_blank">Report a Bug</a>
+    • <a href="https://git.zakscode.com/ztimson/utils/releases" target="_blank">Release Notes</a>
-    • <a href="https://git.zakscode.com/ztimson/persist/issues/new?template=.github%2fissue_template%2fenhancement.md" target="_blank">Request a Feature</a>
+    • <a href="https://git.zakscode.com/ztimson/utils/issues/new?template=.github%2fissue_template%2fbug.md" target="_blank">Report a Bug</a>
+    • <a href="https://git.zakscode.com/ztimson/utils/issues/new?template=.github%2fissue_template%2fenhancement.md" target="_blank">Request a Feature</a>
   </div>
 
   ---

package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "@ztimson/utils",
-	"version": "0.15.6",
+	"version": "0.16.3",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@ztimson/utils",
-			"version": "0.15.6",
+			"version": "0.16.3",
 			"license": "MIT",
 			"devDependencies": {
 				"@types/jest": "^29.5.12",

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ztimson/utils",
-	"version": "0.16.0",
+	"version": "0.16.5",
 	"description": "Utility library",
 	"author": "Zak Timson",
 	"license": "MIT",
@@ -21,7 +21,7 @@
 	},
 	"scripts": {
 		"build": "npx tsc && npx vite build",
-		"docs": "typedoc --plugin typedoc-plugin-markdown --hidePageHeader --out ./docs --entryPoints src/**/*.ts",
+		"docs": "typedoc --plugin typedoc-plugin-markdown --cleanOutputDir false --outputFileStrategy modules --hidePageHeader --out ./docs --entryPoints src/**/*.ts --readme none --entryFileName Home",
 		"test": "npx jest",
 		"test:coverage": "npx jest --coverage",
 		"watch": "npx vite build --watch"

src/cache.ts

@@ -0,0 +1,118 @@
+/**
+ * Map of data which tracks whether it is a complete collection & offers optional expiry of cached values
+ */
+export class Cache<K, T> {
+	private store: any = {};
+
+	/** Whether cache is complete */
+	complete = false;
+
+	/**
+	 * Create new cache
+	 *
+	 * @param {keyof T} key Default property to use as primary key
+	 * @param {number} ttl Default expiry in milliseconds
+	 */
+	constructor(public readonly key: keyof T, public ttl?: number) {
+		return new Proxy(this, {
+			get: (target: this, prop: string | symbol) => {
+				if(prop in target) return (<any>target)[prop];
+				return target.store[prop];
+			},
+			set: (target: any, prop: string | symbol, value: T) => {
+				if(prop in target) target[prop] = value;
+				else target.store[prop] = value;
+				return true;
+			}
+		});
+	}
+
+	private getKey(value: T): K {
+		return <K>value[this.key];
+	}
+
+	/**
+	 * Get all cached items
+	 *
+	 * @return {T[]} Array of items
+	 */
+	all(): T[] {
+		return Object.values(this.store);
+	}
+
+	/**
+	 * Add a new item to the cache. Like set, but finds key automatically
+	 *
+	 * @param {T} value Item to add to cache
+	 * @param {number | undefined} ttl Override default expiry
+	 * @return {this}
+	 */
+	add(value: T, ttl = this.ttl): this {
+		const key = this.getKey(value);
+		this.set(key, value, ttl);
+		return this;
+	}
+
+	/**
+	 * Add several rows to the cache
+	 *
+	 * @param {T[]} rows Several items that will be cached using the default key
+	 * @param complete Mark cache as complete & reliable, defaults to true
+	 * @return {this}
+	 */
+	addAll(rows: T[], complete = true): this {
+		rows.forEach(r => this.add(r));
+		this.complete = complete;
+		return this;
+	}
+
+	/**
+	 * Delete an item from the cache
+	 *
+	 * @param {K} key Item's primary key
+	 */
+	delete(key: K) {
+		delete this.store[key];
+	}
+
+	/**
+	 * Return cache as an array of key-value pairs
+	 * @return {[K, T][]} Key-value pairs array
+	 */
+	entries(): [K, T][] {
+		return <[K, T][]>Object.entries(this.store);
+	}
+
+	/**
+	 * Get a list of cached keys
+	 *
+	 * @return {K[]} Array of keys
+	 */
+	keys(): K[] {
+		return <K[]>Object.keys(this.store);
+	}
+
+	/**
+	 * Add an item to the cache manually specifying the key
+	 *
+	 * @param {K} key Key item will be cached under
+	 * @param {T} value Item to cache
+	 * @param {number | undefined} ttl Override default expiry
+	 * @return {this}
+	 */
+	set(key: K, value: T, ttl = this.ttl): this {
+		this.store[key] = value;
+		if(ttl) setTimeout(() => {
+			this.complete = false;
+			this.delete(key);
+		}, ttl);
+		return this;
+	}
+
+	/**
+	 * Get all cached items
+	 *
+	 * @return {T[]} Array of items
+	 */
+	values = this.all();
+}

src/csv.ts

@@ -0,0 +1,26 @@
+import {dotNotation, flattenObj} from './objects.ts';
+
+/**
+ * Convert an object to a CSV string
+ *
+ * @param {any[]} target Array of objects to create CSV from
+ * @param {boolean} flatten Should nested object be flattened or treated as values
+ * @return {string} CSV string
+ */
+export function csv(target: any[], flatten=true) {
+	const headers = target.reduce((acc, row) => {
+		Object.keys(flatten ? flattenObj(row) : row)
+			.forEach(key => { if(!acc.includes(key)) acc.push(key); });
+		return acc;
+	}, []);
+	return [
+		headers.join(','),
+		...target.map(row => headers.map((h: string) => {
+			const value = dotNotation<any>(row, h);
+			const type = typeof value;
+			if(type == 'string' && value.includes(',')) return `"${value}"`;
+			if(type == 'object') return `"${JSON.stringify(value)}"`;
+			return value;
+		}).join(','))
+	].join('\n');
+}

src/files.ts

@@ -1,33 +1,35 @@
+import {makeArray} from './array.ts';
 import {JSONAttemptParse} from './objects.ts';
 import {PromiseProgress} from './promise-progress';
 
-/**
- * Download a file from a URL
- *
- * @param href URL that will be downloaded
- * @param {string} name Override download name
- */
-export function download(href: any, name?: string) {
-	const a = document.createElement('a');
-	a.href = href;
-	a.download = name || href.split('/').pop();
-	document.body.appendChild(a);
-	a.click();
-	document.body.removeChild(a);
-}
-
 /**
  * Download blob as a file
  *
  * @param {Blob} blob File as a blob
  * @param {string} name Name blob will be downloaded as
  */
-export function downloadBlob(blob: Blob, name: string) {
+export function downloadFile(blob: Blob | string | string[], name: string) {
+	if(!(blob instanceof Blob)) blob = new Blob(makeArray(blob));
 	const url = URL.createObjectURL(blob);
-	download(url, name);
+	downloadUrl(url, name);
 	URL.revokeObjectURL(url);
 }
 
+/**
+ * Download a file from a URL
+ *
+ * @param href URL that will be downloaded
+ * @param {string} name Override download name
+ */
+export function downloadUrl(href: any, name?: string) {
+	const a = document.createElement('a');
+	a.href = href;
+	a.download = name || href.split('/').pop();
+	document.body.appendChild(a);
+	a.click();
+	document.body.removeChild(a);
+}
+
 /**
  * Open filebrowser & return selected file
  *

src/index.ts

@@ -1,5 +1,7 @@
 export * from './array';
 export * from './aset';
+export * from './cache';
+export * from './csv';
 export * from './files';
 export * from './emitter';
 export * from './errors';

src/string.ts

@@ -1,3 +1,5 @@
+import {dotNotation, flattenObj} from './objects.ts';
+
 /**
  * String of all letters
  */
@@ -18,16 +20,6 @@ const SYMBOL_LIST = '~`!@#$%^&*()_-+={[}]|\\:;"\'<,>.?/';
  */
 const CHAR_LIST = LETTER_LIST + NUMBER_LIST + SYMBOL_LIST;
 
-/**
- * Generate a random hexadecimal value
- *
- * @param {number} length Number of hexadecimal place values
- * @return {string} Hexadecimal number as a string
- */
-export function randomHex(length: number) {
-	return Array(length).fill(null).map(() => Math.round(Math.random() * 0xF).toString(16)).join('');
-}
-
 /**
  * Convert number of bytes into a human-readable size
  *
@@ -95,6 +87,16 @@ export function pad(text: any, length: number, char: string = ' ', start = true)
 	return text.toString().padEnd(length, char);
 }
 
+/**
+ * Generate a random hexadecimal value
+ *
+ * @param {number} length Number of hexadecimal place values
+ * @return {string} Hexadecimal number as a string
+ */
+export function randomHex(length: number) {
+	return Array(length).fill(null).map(() => Math.round(Math.random() * 0xF).toString(16)).join('');
+}
+
 /**
  * Generate a string of random characters.
  *

src/time.ts

@@ -39,12 +39,12 @@ export function sleep(ms: number): Promise<void> {
  * await sleepUntil(() => loading); // Won't continue until loading flag is false
  * ```
  *
- * @param {() => boolean} fn Return true to continue
+ * @param {() => boolean | Promise<boolean>} fn Return true to continue
  * @param {number} checkInterval Run function ever x milliseconds
  * @return {Promise<void>} Callback when sleep is over
  */
-export async function sleepUntil(fn : () => boolean, checkInterval=100): Promise<void> {
+export async function sleepUntil(fn : () => boolean | Promise<boolean>, checkInterval = 100): Promise<void> {
-	while(fn()) await sleep(checkInterval);
+	while(await fn()) await sleep(checkInterval);
 }
 
 /**

tests/object.spec.ts

@@ -29,28 +29,6 @@ describe('Object Utilities', () => {
 		});
 	});
 
-	describe('deepCopy', () => {
-		const copy = deepCopy(TEST_OBJECT);
-		test('Array of arrays', () => {
-			const a = [[1, 2], [3, 4]];
-			const b = deepCopy(a);
-			b[0][1] = 5;
-			expect(a).not.toEqual(b);
-		});
-		test('Change array inside object', () => {
-			copy.b[1] = [1, 1, 1];
-			expect(copy.b[1]).not.toEqual(TEST_OBJECT.b[1]);
-		});
-		test('Change object inside object', () => {
-			copy.g = {h: Math.random()};
-			expect(copy.g).not.toEqual(TEST_OBJECT.g);
-		});
-		test('Change object property inside nested array', () => {
-			copy.c.d[0][0].e = -1;
-			expect(copy.c.d[0][0].e).not.toEqual(TEST_OBJECT.c.d[0][0].e);
-		});
-	});
-
 	describe('dotNotation', () => {
 		test('no object or properties', () => {
 			expect(dotNotation(undefined, 'z')).toStrictEqual(undefined);