@lipemat/js-helpers 1.0.0

package/src/error/Readme.md

@@ -0,0 +1,40 @@
+# error
+
+An `Error` subclass that carries per-field messages. Useful for translating `WP_Error` REST API responses into form field errors.
+
+## Exports
+
+### `class ErrorWithFields<T>`
+
+Extends `Error`. Accepts an `ErrorField<T>` (which may include `additional_errors`) and exposes a `fields` map of field code to message. Field codes are normalized (e.g. `user_email` → `email`).
+
+### `ErrorField<T>` (type)
+
+```ts
+interface ErrorField<T> {
+	code: keyof T;
+	data?: object | string | boolean | number;
+	message: string;
+	additional_errors?: Array<ErrorField<T>>;
+}
+```
+
+### `Fields<T>` (type)
+
+```ts
+type Fields<T> = { [field in keyof T]?: string };
+```
+
+## Usage
+
+```ts
+import {ErrorWithFields} from '@lipemat/js-helpers';
+
+type Form = {email: string; username: string};
+
+throw new ErrorWithFields<Form>( {
+	code: 'rest_user_invalid_email',
+	message: 'Invalid email address.',
+} );
+// error.fields.email === 'Invalid email address.'
+```

package/src/error/error.ts

@@ -0,0 +1,49 @@
+export interface ErrorField<T extends { [ field: string ]: string }> {
+	code: keyof T;
+	data?: object | string | boolean | number;
+	message: string;
+
+	additional_errors?: Array<ErrorField<T>>;
+}
+
+export type Fields<T> = {
+	[field in keyof T]?: string;
+};
+
+/**
+ * Use in place from the default Error handler to include
+ * information about form fields which caused the errors.
+ *
+ * Translates `WP_Error` responses from REST API into
+ * field name and their corresponding messages.
+ *
+ * @version 1.2.1
+ */
+export class ErrorWithFields<T extends { [ field: string ]: string }> extends Error {
+	public fields: Fields<T>;
+
+	constructor( error: ErrorField<T> ) {
+		const errors = [ error ];
+		if ( undefined !== error.additional_errors ) {
+			errors.push( ...error.additional_errors );
+		}
+
+		super( errors.map( er => er.message ).join( ' ' ) );
+
+		this.name = 'ErrorWithData';
+		this.fields = {};
+		errors.forEach( field => {
+			this.fields[ this.translate( field ).code ] = field.message;
+		} );
+	}
+
+	translate( error: ErrorField<T> ): ErrorField<T> {
+		error.code = error.code
+			.toString()
+			.replace( 'user_name', 'username' )
+			.replace( 'user_email', 'email' )
+			.replace( 'rest_user_invalid_email', 'email' );
+
+		return error;
+	}
+}

package/src/escaping/Readme.md

@@ -0,0 +1,23 @@
+# escaping
+
+Decode HTML entities in a string. Taken nearly verbatim from Gutenberg's `@wordpress/html-entities`, with the input sanitized through [DOMPurify](https://github.com/cure53/DOMPurify).
+
+## Exports
+
+### `decodeEntities( html ): string`
+
+Return `html` with HTML entities decoded. Strings without a `&` are returned unchanged. A reusable detached `<textarea>` is used for decoding.
+
+- `html: string` — string that may contain HTML entities.
+
+## Usage
+
+```ts
+import {decodeEntities} from '@lipemat/js-helpers';
+
+decodeEntities( 'Ben &amp; Jerry&#039;s' ); // "Ben & Jerry's"
+```
+
+## Notes
+
+Requires a DOM (`document`); intended for browser use.

package/src/escaping/escaping.ts

@@ -0,0 +1,41 @@
+import DOMPurify from 'dompurify';
+
+let _decodeTextArea: HTMLTextAreaElement;
+
+/**
+ * Taken nearly verbatim from the Gutenberg package.
+ *
+ * Added to the helpers in case we are
+ * not loading wp-html-entities on the front-end.
+ *
+ * @notice We likely are loading wp-html-entities unless a special project.
+ *
+ * @see @wordpress/html-entities
+ *
+ * @version 1.0.5
+ *
+ * @link https://github.com/WordPress/gutenberg/blob/d5915916abc45e6682f4bdb70888aa41e98aa395/packages/html-entities/src/index.js#L14
+ * @param  html
+ */
+export function decodeEntities( html: string ) {
+	// Not a string, or no entities to decode.
+	if ( -1 === html.indexOf( '&' ) ) {
+		return html;
+	}
+
+	// Create a textarea for decoding entities, that we can reuse.
+	if ( undefined === _decodeTextArea ) {
+		if ( undefined !== document.implementation ) {
+			_decodeTextArea = document.implementation
+				.createHTMLDocument( '' )
+				.createElement( 'textarea' );
+		} else {
+			_decodeTextArea = document.createElement( 'textarea' );
+		}
+	}
+
+	_decodeTextArea.innerHTML = DOMPurify.sanitize( html );
+	const decoded = _decodeTextArea.textContent;
+	_decodeTextArea.innerHTML = '';
+	return ( decoded );
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Public entry point for `@lipemat/js-helpers`.
+ *
+ * Re-exports the public API of every helper so consumers can use
+ * `import {<helper>} from '@lipemat/js-helpers'`.
+ */
+export * from './classes/classes.js';
+export * from './colors/colors.js';
+export * from './csvExport/csvExport.js';
+export * from './date/date.js';
+export * from './debounce/debounce.js';
+export * from './delay/delay.js';
+export * from './device/device.js';
+export * from './dom-ready/dom-ready.js';
+export * from './error/error.js';
+export * from './escaping/escaping.js';
+export * from './injectScript/injectScript.js';
+export * from './memoize/memoize.js';
+export * from './noop/noop.js';
+export * from './objects/objects.js';
+export * from './once/once.js';
+export * from './string/string.js';
+export * from './throttle/throttle.js';
+export * from './url/url.js';

package/src/injectScript/Readme.md

@@ -0,0 +1,26 @@
+# injectScript
+
+Inject an external script into the DOM once. Memoized by `src`, so repeated calls with the same URL reuse the same promise instead of adding the script again.
+
+## Exports
+
+### `injectScript( src, inBody? )`
+
+- `src: string` — URL of the script to inject.
+- `inBody?: boolean` — append to `<body>` instead of `<head>`. Defaults to `false`.
+
+Returns a `Promise` that resolves when the script loads and rejects on error or abort.
+
+## Usage
+
+```ts
+import {injectScript} from '@lipemat/js-helpers';
+
+await injectScript( 'https://example.com/widget.js' );
+// Calling again with the same URL reuses the first promise.
+await injectScript( 'https://example.com/widget.js' );
+```
+
+## Notes
+
+Requires a DOM (`document`); intended for browser use.

package/src/injectScript/injectScript.ts

@@ -0,0 +1,31 @@
+import {memoize} from '../memoize/memoize.js';
+
+/**
+ * Inject a script into the DOM.
+ *
+ * May be called multiple times and will ony inject the script once.
+ *
+ * @param {string}  $src    - URL of the script.
+ * @param {boolean} $inBody - Put in body tag instead of head
+ *
+ * @version 1.2.1
+ *
+ * @return {Promise}
+ */
+export const injectScript = memoize( ( src, inBody: boolean = false ) => {
+	return new Promise( ( resolve, reject ) => {
+		const script = document.createElement( 'script' );
+		script.async = false;
+		script.src = src;
+		script.addEventListener( 'load', () => resolve( 'Loaded: ' + src ) );
+		script.addEventListener( 'error', () => reject( 'Error loading script.' ) );
+		script.addEventListener( 'abort', () =>
+			reject( 'Script loading aborted.' ),
+		);
+		if ( inBody ) {
+			document.body.appendChild( script );
+		} else {
+			document.head.appendChild( script );
+		}
+	} );
+} );

package/src/memoize/Readme.md

@@ -0,0 +1,28 @@
+# memoize
+
+Lodash-free memoization. Caches results of `fn` keyed by the first argument, or by a custom `resolver`.
+
+## Exports
+
+### `memoize( fn, resolver? )`
+
+- `fn: T` — function whose results are cached.
+- `resolver?: ( ...args ) => string` — derive a custom cache key. Defaults to the first argument.
+
+Returns the memoized function with a `.cache` `Map` you can inspect or clear.
+
+### `MemoizedFunction<T>` (type)
+
+The returned function type, including the `cache: Map<string, ReturnType<T>>` property.
+
+## Usage
+
+```ts
+import {memoize} from '@lipemat/js-helpers';
+
+const slugify = memoize( ( value: string ) => value.toLowerCase().replace( /\s+/g, '-' ) );
+
+slugify( 'Hello World' ); // computed
+slugify( 'Hello World' ); // from cache
+slugify.cache.clear();
+```

package/src/memoize/memoize.ts

@@ -0,0 +1,27 @@
+import type {Callback, Return} from '../once/once.js';
+
+type Resolver<T extends Callback> = ( ...args: Parameters<T> ) => string;
+
+export type MemoizedFunction<T extends Callback> = Return<T> & {
+	cache: Map<string, ReturnType<T>>;
+};
+
+/**
+ * Similar to lodash memoize but without requiring lodash.
+ *
+ * @version 1.1.3
+ */
+export function memoize<T extends Callback>( fn: T, resolver?: Resolver<T> ): MemoizedFunction<T> {
+	const memoized = function( ...args: Parameters<T> ): ReturnType<Callback> {
+		const key = resolver ? resolver( ...args ) : args[ 0 ];
+		if ( memoized.cache.has( key ) ) {
+			return memoized.cache.get( key );
+		}
+
+		const result = fn( ...args );
+		memoized.cache = memoized.cache.set( key, result );
+		return result;
+	};
+	memoized.cache = new Map();
+	return memoized;
+}

package/src/noop/Readme.md

@@ -0,0 +1,19 @@
+# noop
+
+A no-operation function. Lodash-free replacement for `lodash.noop`. Useful as a default callback.
+
+## Exports
+
+### `noop(): void`
+
+Does nothing.
+
+## Usage
+
+```ts
+import {noop} from '@lipemat/js-helpers';
+
+function setup( {onChange = noop} = {} ) {
+	onChange();
+}
+```

package/src/noop/noop.ts

@@ -0,0 +1,9 @@
+/**
+ * No operation function.
+ *
+ * Similar to lodash noop but without requiring lodash.
+ *
+ * @version 1.0.0
+ */
+export const noop = () => {
+};

package/src/objects/Readme.md

@@ -0,0 +1,31 @@
+# objects
+
+Type-safe wrappers around `Object.keys` and `Object.entries` that preserve key types.
+
+> More robust versions are available from the `@lipemat/js-boilerplate-gutenberg` package.
+
+## Exports
+
+### `keysOf( obj ): Array<keyof T>`
+
+Like `Object.keys` but typed as `Array<keyof T>` instead of `string[]`.
+
+### `entriesOf( obj ): Array<[keyof T, T[keyof T]]>`
+
+Like `Object.entries` but typed as `Array<[keyof T, T[keyof T]]>`.
+
+## Usage
+
+```ts
+import {keysOf, entriesOf} from '@lipemat/js-helpers';
+
+const config = {width: 100, label: 'box'};
+
+keysOf( config ).forEach( key => {
+	// key is 'width' | 'label'
+} );
+
+entriesOf( config ).forEach( ( [ key, value ] ) => {
+	// fully typed key/value pair
+} );
+```

package/src/objects/objects.ts

@@ -0,0 +1,26 @@
+/**
+ * @notice More robust versions are available from the `@lipemat/js-boilerplate-gutenberg` package.
+ */
+
+/**
+ * Object.keys() with type inference.
+ *
+ * Instead of getting `string[]` we get `keyof T[]`.
+ *
+ * @since 4.3.0
+ */
+export function keysOf<T extends object>( obj: T ): Array<keyof T> {
+	return Object.keys( obj ) as Array<keyof T>;
+}
+
+
+/**
+ * Object.entries() with type inference.
+ *
+ * Instead of getting `Array<[string, any]>` we get `Array<[keyof T, T[keyof T]]>`.
+ *
+ * @since 4.3.0
+ */
+export function entriesOf<T extends object>( obj: T ): Array<[ keyof T, T[keyof T] ]> {
+	return Object.entries( obj ) as Array<[ keyof T, T[keyof T] ]>;
+}

package/src/once/Readme.md

@@ -0,0 +1,26 @@
+# once
+
+Lodash-free `once`. Wrap a function so it only runs the first time; subsequent calls return the cached result.
+
+## Exports
+
+### `once( fn ): Return<T>`
+
+- `fn: T` — function to run a single time.
+
+Returns a function with the same signature that caches and returns the first result.
+
+### `Callback` / `Return<T>` (types)
+
+Shared function-shape types used by `once`, `debounce`, `throttle`, and `memoize`.
+
+## Usage
+
+```ts
+import {once} from '@lipemat/js-helpers';
+
+const init = once( () => expensiveSetup() );
+
+init(); // runs expensiveSetup()
+init(); // returns the first result, no re-run
+```

package/src/once/once.ts

@@ -0,0 +1,22 @@
+// eslint-disable-next-line -- Only being used for a shape to guarantee the other types.
+export type Callback = ( ...args: Array<any> ) => any;
+export type Return<T extends Callback> = ( ...args: Parameters<T> ) => ReturnType<T>
+
+/**
+ * Similar to lodash once but without requiring lodash.
+ *
+ * @version 1.0.2
+ */
+export function once<T extends Callback>( fn: T ): Return<T> {
+	let result: ReturnType<T>;
+	let called = false;
+
+	return ( ...args: Parameters<T> ) => {
+		if ( ! called ) {
+			called = true;
+			result = fn( ...args );
+		}
+
+		return result;
+	};
+}

package/src/string/Readme.md

@@ -0,0 +1,37 @@
+# string
+
+Small string helpers for random keys and slash management.
+
+> More robust versions are available from the `@lipemat/js-boilerplate-gutenberg` package.
+
+## Exports
+
+### `generateRandomKey( length? ): string`
+
+Return a random alphanumeric string. `length` defaults to `10`.
+
+### `addLeadingSlash( url ): string`
+
+Ensure `url` starts with a slash. Empty/whitespace input is returned unchanged.
+
+### `addTrailingSlash( url ): string`
+
+Ensure `url` ends with a slash. Empty/whitespace input is returned unchanged.
+
+### `removeLeadingSlash( url ): string`
+
+Remove a leading slash if present. Empty/whitespace input is returned unchanged.
+
+### `removeTrailingSlash( url ): string`
+
+Remove a trailing slash if present. Empty/whitespace input is returned unchanged.
+
+## Usage
+
+```ts
+import {generateRandomKey, addTrailingSlash, removeLeadingSlash} from '@lipemat/js-helpers';
+
+generateRandomKey(); // e.g. 'a8Kd0Lm2Qz'
+addTrailingSlash( 'path/to' ); // 'path/to/'
+removeLeadingSlash( '/path' ); // 'path'
+```

package/src/string/string.ts

@@ -0,0 +1,72 @@
+/**
+ * @notice More robust versions are available from the `@lipemat/js-boilerplate-gutenberg` package.
+ */
+
+/**
+ * Generate a random key of a given length.
+ *
+ * @version 1.0.0
+ */
+export function generateRandomKey( length: number = 10 ) {
+	const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+	let result = '';
+	for ( let i = 0; i < length; i++ ) {
+		result += characters.charAt( Math.floor( Math.random() * characters.length ) );
+	}
+	return result;
+}
+
+
+/**
+ * Adds a leading slash to a URL if it doesn't already have one.
+ *
+ * @version 1.0.0
+ */
+export function addLeadingSlash( url: string ): string {
+	const trimmedURL = url.trim();
+	if ( '' === trimmedURL ) {
+		return url;
+	}
+	return url?.replace( /^\/?/, '/' );
+}
+
+
+/**
+ * Adds a trailing slash to a URL if it doesn't already have one.
+ *
+ * @version 1.0.0
+ */
+export function addTrailingSlash( url: string ): string {
+	const trimmedURL = url.trim();
+	if ( '' === trimmedURL ) {
+		return url;
+	}
+	return url.replace( /\/?$/, '/' );
+}
+
+
+/**
+ * Removes a leading slash from a URL if it has one.
+ *
+ * @version 1.0.0
+ */
+export function removeLeadingSlash( url: string ): string {
+	const trimmedURL = url.trim();
+	if ( '' === trimmedURL ) {
+		return url;
+	}
+	return url.replace( /^\//, '' );
+}
+
+/**
+ * Removes a trailing slash from a URL if it has one.
+ *
+ * @version 1.0.0
+ */
+export function removeTrailingSlash( url: string ): string {
+	const trimmedURL = url.trim();
+	if ( '' === trimmedURL ) {
+		return url;
+	}
+	return url.replace( /\/$/, '' );
+}

package/src/throttle/Readme.md

@@ -0,0 +1,27 @@
+# throttle
+
+Lodash-free throttle. Ensures `fn` runs at most once per `wait` ms.
+
+## Exports
+
+### `throttle( fn, wait? )`
+
+- `fn: T` — function to throttle.
+- `wait?: number` — minimum delay between calls in milliseconds, defaults to `300`.
+
+Returns a throttled function plus:
+
+- `.immediate( ...args )` — run `fn` right away, bypassing the wait.
+- `.cancel()` — cancel a pending trailing call.
+
+## Usage
+
+```ts
+import {throttle} from '@lipemat/js-helpers';
+
+const onScroll = throttle( () => update(), 100 );
+window.addEventListener( 'scroll', onScroll );
+
+onScroll.immediate(); // run now
+onScroll.cancel(); // cancel a pending call
+```

package/src/throttle/throttle.ts

@@ -0,0 +1,57 @@
+import type {Callback, Return} from '../once/once.js';
+
+type Result<T extends Callback> = {
+	( ...args: Parameters<T> ): ReturnType<T>;
+	immediate: ( ...args: Parameters<T> ) => ReturnType<T>;
+	cancel: () => void;
+};
+
+/**
+ * Alternative to lodash throttle.
+ *
+ * - Additional support for `immediate` execution to bypass the wait time.
+ * - Returns a promise to allow waiting for a completion of the throttled function.
+ *
+ * @version 1.0.1
+ */
+export function throttle<T extends Callback>( fn: T, wait = 300 ): Result<T> {
+	let lastTime = 0;
+	let timer: number | NodeJS.Timeout | undefined;
+	let result: ReturnType<T>;
+
+	const throttled = function( ...args: Parameters<T> ): Promise<ReturnType<T>> {
+		const now = Date.now();
+		const remaining = now - lastTime;
+
+		if ( remaining >= wait ) {
+			clearTimeout( timer );
+			timer = undefined;
+			lastTime = now;
+			return fn( ...args );
+		}
+
+		if ( 'undefined' === typeof timer ) {
+			timer = setTimeout( () => {
+				lastTime = Date.now();
+				result = fn( ...args );
+				timer = undefined;
+			}, wait - remaining );
+		}
+
+		return result;
+	};
+
+	// Immediate execution method.
+	throttled.immediate = function( ...args: Parameters<T> ): Return<T> {
+		clearTimeout( timer );
+		lastTime = Date.now();
+		return fn( ...args );
+	};
+
+	// Cancel method.
+	throttled.cancel = function() {
+		clearTimeout( timer );
+	};
+
+	return throttled as Result<T>;
+}

package/src/url/Readme.md

@@ -0,0 +1,32 @@
+# url
+
+Read and append URL query arguments. Inputs are sanitized through [DOMPurify](https://github.com/cure53/DOMPurify).
+
+> More robust versions are available from the `@lipemat/js-boilerplate-gutenberg` and `@wordpress/url` packages.
+
+## Exports
+
+### `getUrlParam( parameter, defaultValue? ): string | null`
+
+Return the value of `parameter` from the current `window.location.search`, or `defaultValue` (default `''`) when it is absent.
+
+### `addQueryArgs( url?, args ): string`
+
+Append `args` to `url` as query parameters and return the resulting URL string.
+
+- `url?: string` — base URL, defaults to `''`.
+- `args: { [name: string]: string | number }` — parameters to append.
+
+## Usage
+
+```ts
+import {getUrlParam, addQueryArgs} from '@lipemat/js-helpers';
+
+getUrlParam( 'page', '1' ); // current ?page value or '1'
+addQueryArgs( 'https://example.com', {page: 2, sort: 'name'} );
+// 'https://example.com/?page=2&sort=name'
+```
+
+## Notes
+
+`getUrlParam` requires `window`; intended for browser use.