@future-widget-lab/ui-keys

A helper for creating render-friendly keys, useful for uniquely identifying resources, caching, testing, and rendering. Generated keys can also be parsed back into their original components.

Features

• Generates structured, deterministic keys for various use cases.
• Supports strings, numbers, booleans, arrays, and objects.
• Converts nullish values into a standard placeholder ("unknown").
• Provides a parser (parseUiKey) to revert keys back to their original components.

Installation

npm install @future-widget-lab/ui-keys

Usage

Creating a UI Key

import { createUiKey } from '@future-widget-lab/ui-keys';

const key1 = createUiKey('user', 42);
console.log(key1); // "user::42"

const key2 = createUiKey('post', { id: 123, category: 'tech' });
console.log(key2); // "post::@{"id":123,"category":"tech"}"

Parsing a UI Key

import { parseUiKey } from '@future-widget-lab/ui-keys';

const parsedKey = parseUiKey(`post::@{"id":123,"category":"tech"}`);
console.log(parsedKey); // ["post", { id: 123, category: "tech" }]

API Reference

createUiKey(...args: unknown[]): string

Generates a structured key from the provided arguments.

• Strings, numbers, and booleans are converted to their string representations.
• Objects and arrays are serialized using flatted.
• Nullish values (like null and undefined) are replaced with "unknown".

Parameters

Parameter	Type	Description
...args	unknown[]	Values to be included in the generated key.

parseUiKey(key: string): unknown[]

Parses a UI key back into its original components.

• Splits the key into its original components.
• Converts numeric and boolean values back to their types.
• Parses objects and arrays serialized with flatted.
• "unknown" is converted to null.

Parameters

Parameter	Type	Description
key	string	The UI key to be parsed.

License

MIT