Dimension
utils 0.1.0
Install from the command line:
Learn more about npm packages
$ npm install @dimensiondev/utils@0.1.0
Install via package.json:
"@dimensiondev/utils": "0.1.0"
About this version
A collection of shared utility functions for Firefly projects. Provides browser-safe utilities, promise helpers, and common patterns used across the ecosystem.
- 🌐 Browser-safe: All utilities work in both browser and server environments
- 🎯 Type-safe: Full TypeScript support with strict typing
- 📦 Tree-shakable: Import only what you need
- 🔄 Promise utilities: Advanced promise manipulation helpers
- 🛡️ SSR-safe: Safe to use in server-side rendering environments
# Using pnpm (recommended for workspace)
pnpm add @dimensiondev/utils
# Using npm
npm install @dimensiondev/utils
# Using yarn
yarn add @dimensiondev/utilsSafe access to browser APIs that return null in non-browser environments.
import { bom } from '@dimensiondev/utils';
// Safe access to browser APIs
if (bom.window) {
console.log('Running in browser');
}
if (bom.document) {
const element =
bom.document.getElementById('my-element');
}
if (bom.localStorage) {
bom.localStorage.setItem('key', 'value');
}Available properties:
-
bom.window- Window object or null -
bom.document- Document object or null -
bom.location- Location object or null -
bom.navigator- Navigator object or null -
bom.localStorage- LocalStorage object or null
Creates a deferred promise that can be resolved or rejected externally.
import { defer } from '@dimensiondev/utils';
const [promise, resolve, reject] = defer<string>();
// Later in your code...
setTimeout(() => {
resolve('Hello World!');
}, 1000);
const result = await promise; // 'Hello World!'Returns: [Promise<T>, resolve, reject]
Adds a timeout to any promise, preventing it from hanging indefinitely.
import { timeout } from '@dimensiondev/utils';
try {
// Timeout after 5 seconds
const data = await timeout(
fetch('/api/slow-endpoint'),
5000,
'API request timeout',
);
} catch (error) {
console.error(error.message); // 'API request timeout'
}Parameters:
-
promise- The promise to add timeout to -
time- Timeout in milliseconds -
rejectReason- Optional custom error message (defaults to "timeout")
Returns: Promise<T> that either resolves with the original promise or rejects with timeout error
import { bom } from '@dimensiondev/utils';
function updateTitle(newTitle: string) {
if (bom.document) {
bom.document.title = newTitle;
}
}
function getCurrentUrl(): string | null {
return bom.location?.href || null;
}import { defer, timeout } from '@dimensiondev/utils';
// Create a promise that can be resolved later
const [dataReady, signalDataReady] = defer<Data>();
// Add timeout protection
const dataWithTimeout = timeout(
dataReady,
10000,
'Data loading timeout',
);
// Somewhere else in your code
fetchData().then((data) => {
signalDataReady(data);
});import { defer, bom } from '@dimensiondev/utils';
function waitForWindowLoad(): Promise<Window> {
if (!bom.window) {
throw new Error('Not in browser environment');
}
if (bom.document?.readyState === 'complete') {
return Promise.resolve(bom.window);
}
const [promise, resolve] = defer<Window>();
const handleLoad = () => {
resolve(bom.window!);
};
bom.window.addEventListener('load', handleLoad, {
once: true,
});
return promise;
}All utilities come with full TypeScript support and type definitions.
import {
defer,
timeout,
bom,
type DeferTuple,
} from '@dimensiondev/utils';
// Type-safe deferred promise
const [promise, resolve, reject]: DeferTuple<User> =
defer<User>();
// Type-safe timeout with proper error handling
const user: User = await timeout(fetchUser(), 5000);
// Type-safe BOM access
if (bom.window) {
// TypeScript knows this is Window | null
bom.window.location.href = '/redirect';
}MIT
