npm package: @regardio/js
Description: Regardio JavaScript utilities
Author: Bernd Matzner
Latest version: 0.10.0

# @regardio/js

> **TypeScript utilities for Regardio applications**

A collection of lightweight, tree-shakeable utility functions for common tasks
like text manipulation, HTTP handling, internationalization, time formatting, and validation.

## ⚠️ Pre-release Notice

**This package is currently in pre-release (v0.x).** While we use these utilities in production across our own projects, the API may still change between minor versions. We recommend:

- Pinning to exact versions in your `package.json`
- Reviewing changelogs before upgrading
- Expecting potential breaking changes until v1.0

## Why This Package?

We created `@regardio/js` to:

- **Share battle-tested utilities** — These functions power real Regardio projects and have been refined through actual use
- **Reduce boilerplate** — Common patterns like text formatting, cookie handling, language detection, and time formatting in one place
- **Stay framework-agnostic** — Works with any JavaScript/TypeScript project (React, Node, Deno, etc.)
- **Enable tree-shaking** — Import only what you need; unused utilities won't bloat your bundle

## Installation

```bash
pnpm add @regardio/js
```

## Modules

### @regardio/js/text

String manipulation and formatting utilities.

```ts
import {
  typographicQuotes,
  truncateText,
  splitIntoSentences,
  formatBytes,
  parseAuthorString,
} from '@regardio/js/text';

typographicQuotes('"Hello"', 'de'); // „Hello"
truncateText('Hello world', 8); // "Hello..."
formatBytes(1500000); // "1.5 MB"
parseAuthorString('John <john@example.com>'); // { name: 'John', email: 'john@example.com' }
```

### @regardio/js/time

Date, time, and async utilities.

```ts
import {
  timeAgo,
  friendlyDuration,
  oneWeekFromNow,
  delay,
  measure,
} from '@regardio/js/time';

timeAgo(new Date('2024-01-01')); // "3 months ago"
friendlyDuration(150, 'en', true); // { key: 'common:duration.hoursAndMinutesShort', vars: {...} }
await delay(1000); // Wait 1 second
await measure('fetchData', () => fetch('/api')); // Logs timing
```

### @regardio/js/http

HTTP, cookie, and routing utilities.

```ts
import {
  // Client-side cookies (async - Cookie Store API + fallback)
  getCookie,
  setCookie,
  deleteCookie,
  // Client-side cookies (sync - document.cookie only)
  getCookieSync,
  setCookieSync,
  deleteCookieSync,
  // Server-side cookies (Request/Response)
  parseCookies,
  serializeCookie,
  getCookieFromRequest,
  setCookieOnResponse,
  deleteCookieFromResponse,
  getAllCookiesFromRequest,
  // HTTP utilities
  createDomain,
  getCleanUrl,
  isRouteActive,
} from '@regardio/js/http';

// Client-side async: Cookie Store API with document.cookie fallback
await setCookie('theme', 'dark', { path: '/', secure: true, sameSite: 'lax' });
const theme = await getCookie('theme');
await setCookie('theme', 'light', { path: '/' }); // Update by setting again
await deleteCookie('theme', { path: '/' });

// Client-side sync: document.cookie only (no async/await needed)
setCookieSync('theme', 'dark', { path: '/', secure: true, sameSite: 'lax' });
const themeSync = getCookieSync('theme');
setCookieSync('theme', 'light', { path: '/' }); // Update by setting again
deleteCookieSync('theme', { path: '/' });

// Server-side: Request/Response cookie handling
const session = getCookieFromRequest(request, 'session');
const allCookies = getAllCookiesFromRequest(request);
const response = setCookieOnResponse(
  new Response('OK'),
  'session',
  'abc123',
  { httpOnly: true, secure: true, sameSite: 'lax' }
);

const domain = createDomain(request); // "https://example.com"
isRouteActive('/account', '/account/settings', false); // true
```

### @regardio/js/intl

Server-side language detection for i18n.

```ts
import { LanguageDetector } from '@regardio/js/intl';

const detector = new LanguageDetector({
  supportedLanguages: ['en', 'de'],
  fallbackLanguage: 'en',
});

const locale = await detector.detect(request);
```

### @regardio/js/assert

Runtime assertion and validation utilities.

```ts
import { invariant, invariantResponse, verifyAccept } from '@regardio/js/assert';

invariant(user, 'User not found'); // Throws Error if falsy
invariantResponse(user, 'User not found', { status: 404 }); // Throws Response
verifyAccept('image/png', 'image/*'); // true
```

### @regardio/js/encoding

Binary encoding utilities.

```ts
import { urlBase64ToUint8Array } from '@regardio/js/encoding';

const bytes = urlBase64ToUint8Array(vapidPublicKey);
```

## Module Overview

| Module | Description |
|--------|-------------|
| `@regardio/js/text` | String manipulation, formatting, author parsing |
| `@regardio/js/time` | Time formatting, delays, performance measurement |
| `@regardio/js/http` | Cookies, domain extraction, route matching |
| `@regardio/js/intl` | Server-side language detection for i18n |
| `@regardio/js/assert` | Runtime assertions and MIME validation |
| `@regardio/js/encoding` | Base64 and binary conversions |

## Contributing

This package is primarily maintained for Regardio's internal use, but we welcome:

- Bug reports and fixes
- Documentation improvements
- Feature suggestions (though we may not implement all requests)

## License

**MIT License** — Free to use in commercial and open source projects.

---

*Part of the [Regardio Ensemble](https://regard.io/ensemble) toolkit for
shared well-being.*