@ewanc26/utils 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @ewanc26/utils
+
+Shared utility functions extracted from [ewancroft.uk](https://ewancroft.uk). Zero runtime dependencies.
+
+## Modules
+
+- **Date & Locale** — `formatRelativeTime`, `formatLocalizedDate`, `getUserLocale`
+- **Number Formatting** — `formatCompactNumber`, `formatNumber`
+- **URL Utilities** — `getDomain`, `atUriToBlueskyUrl`, `getBlueskyProfileUrl`, `isExternalUrl`
+- **Validators & Text** — `isValidTid`, `isValidDid`, `truncateText`, `escapeHtml`, `getInitials`, `debounce`, `throttle`
+- **RSS Generation** — `generateRSSFeed`, `generateRSSItem`, `createRSSResponse`, `escapeXml`, `normalizeCharacters`, `formatRSSDate`
+
+## Installation
+
+```bash
+pnpm add @ewanc26/utils
+```
+
+## Quick Examples
+
+```typescript
+import { formatRelativeTime, formatCompactNumber, getDomain, isValidDid, generateRSSFeed } from '@ewanc26/utils';
+
+formatRelativeTime('2025-11-13T00:00:00Z'); // '3d ago'
+formatCompactNumber(1500);                   // '1.5K'
+getDomain('https://www.example.com/path');   // 'example.com'
+isValidDid('did:plc:abc123');                // true
+
+const xml = generateRSSFeed({ title: 'My Blog', link: 'https://mysite.com', description: '…' }, items);
+```
+
+All functions are SSR-safe and fall back to `en-GB` when `navigator` / `window` are unavailable.
+
+## Build
+
+```bash
+pnpm build   # tsc
+pnpm dev     # tsc --watch
+pnpm check   # tsc --noEmit
+```
+
+## Licence
+
+See the root [LICENSE](../../LICENSE).

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@ewanc26/utils",
+  "version": "0.1.0",
+  "description": "Shared utility functions extracted from ewancroft.uk",
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "dev": "tsc --project tsconfig.json --watch",
+    "check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/formatDate.ts

@@ -0,0 +1,25 @@
+/**
+ * Formats a date string into a relative, human-readable time.
+ * Uses the user's system locale where possible, with a fallback to en-GB.
+ */
+export function formatRelativeTime(dateString: string): string {
+	const date = new Date(dateString);
+	const now = new Date();
+	const diffMs = now.getTime() - date.getTime();
+	const diffMins = Math.floor(diffMs / 60000);
+	const diffHours = Math.floor(diffMins / 60);
+	const diffDays = Math.floor(diffHours / 24);
+
+	if (diffMins < 1) return 'just now';
+	if (diffMins < 60) return `${diffMins}m ago`;
+	if (diffHours < 24) return `${diffHours}h ago`;
+	if (diffDays < 7) return `${diffDays}d ago`;
+
+	const userLocale = typeof navigator !== 'undefined' ? navigator.language : 'en-GB';
+
+	return date.toLocaleDateString(userLocale, {
+		day: 'numeric',
+		month: 'short',
+		year: date.getFullYear() !== now.getFullYear() ? 'numeric' : undefined
+	});
+}

package/src/formatNumber.ts

@@ -0,0 +1,35 @@
+/**
+ * Number formatting utilities
+ */
+
+function getLocale(locale?: string): string {
+	return locale || (typeof navigator !== 'undefined' && navigator.language) || 'en-GB';
+}
+
+export function formatCompactNumber(num?: number, locale?: string): string {
+	if (num === undefined || num === null) return '0';
+	const effectiveLocale = getLocale(locale);
+
+	if (num >= 1000) {
+		const divisor = num >= 1000000000 ? 1000000000 : num >= 1000000 ? 1000000 : 1000;
+		const roundedDown = Math.floor((num / divisor) * 10) / 10;
+		const adjustedNum = roundedDown * divisor;
+
+		return new Intl.NumberFormat(effectiveLocale, {
+			notation: 'compact',
+			compactDisplay: 'short',
+			maximumFractionDigits: 1
+		}).format(adjustedNum);
+	}
+
+	return new Intl.NumberFormat(effectiveLocale, {
+		notation: 'compact',
+		compactDisplay: 'short',
+		maximumFractionDigits: 1
+	}).format(num);
+}
+
+export function formatNumber(num: number, locale?: string): string {
+	const effectiveLocale = getLocale(locale);
+	return new Intl.NumberFormat(effectiveLocale).format(num);
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './formatDate';
+export * from './formatNumber';
+export * from './url';
+export * from './validators';
+export * from './rss';
+export * from './locale';

package/src/locale.ts

@@ -0,0 +1,16 @@
+export function getUserLocale(): string {
+	if (typeof navigator !== 'undefined') {
+		return navigator.language || 'en-GB';
+	}
+	return 'en-GB';
+}
+
+export function formatLocalizedDate(dateString: string, locale?: string): string {
+	const date = new Date(dateString);
+	const userLocale = locale || getUserLocale();
+	return date.toLocaleDateString(userLocale, {
+		month: 'short',
+		day: 'numeric',
+		year: 'numeric'
+	});
+}

package/src/rss.ts

@@ -0,0 +1,166 @@
+/**
+ * RSS Feed Generation Utilities
+ */
+
+export interface RSSChannelConfig {
+	title: string;
+	link: string;
+	description: string;
+	language?: string;
+	selfLink?: string;
+	copyright?: string;
+	managingEditor?: string;
+	webMaster?: string;
+	generator?: string;
+	ttl?: number;
+}
+
+export interface RSSItem {
+	title: string;
+	link: string;
+	guid?: string;
+	pubDate: Date | string;
+	description?: string;
+	content?: string;
+	author?: string;
+	categories?: string[];
+	enclosure?: {
+		url: string;
+		length?: number;
+		type?: string;
+	};
+	comments?: string;
+	source?: {
+		url: string;
+		title: string;
+	};
+}
+
+export function escapeXml(unsafe: string): string {
+	return unsafe.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+export function escapeXmlAttribute(unsafe: string): string {
+	return unsafe
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;');
+}
+
+export function normalizeCharacters(text: string): string {
+	return text
+		.replace(/\u2018|\u2019|\u201A|\u201B/g, "'")
+		.replace(/\u201C|\u201D|\u201E|\u201F/g, '"')
+		.replace(/\u2013/g, '-')
+		.replace(/\u2014/g, '--')
+		.replace(/\u00A0/g, ' ')
+		.replace(/\u2026/g, '...')
+		.replace(/\u2022/g, '*')
+		.replace(/&apos;/g, "'")
+		.replace(/&quot;/g, '"')
+		.replace(/&nbsp;/g, ' ')
+		.replace(/&mdash;/g, '--')
+		.replace(/&ndash;/g, '-')
+		.replace(/&hellip;/g, '...')
+		.replace(/&rsquo;/g, "'")
+		.replace(/&lsquo;/g, "'")
+		.replace(/&rdquo;/g, '"')
+		.replace(/&ldquo;/g, '"');
+}
+
+export function formatRSSDate(date: Date | string): string {
+	const d = typeof date === 'string' ? new Date(date) : date;
+	return d.toUTCString();
+}
+
+export function generateRSSItem(item: RSSItem): string {
+	const guid = item.guid || item.link;
+	const pubDate = formatRSSDate(item.pubDate);
+	const title = escapeXml(normalizeCharacters(item.title));
+	const description = item.description ? escapeXml(normalizeCharacters(item.description)) : '';
+	const content = item.content ? normalizeCharacters(item.content) : '';
+	const author = item.author ? escapeXml(normalizeCharacters(item.author)) : '';
+	const categories =
+		item.categories
+			?.map((cat) => `      <category>${escapeXml(normalizeCharacters(cat))}</category>`)
+			.join('\n') || '';
+
+	let enclosure = '';
+	if (item.enclosure) {
+		const length = item.enclosure.length ? ` length="${item.enclosure.length}"` : '';
+		const type = item.enclosure.type ? ` type="${escapeXmlAttribute(item.enclosure.type)}"` : '';
+		enclosure = `      <enclosure url="${escapeXmlAttribute(item.enclosure.url)}"${length}${type} />`;
+	}
+
+	let source = '';
+	if (item.source) {
+		source = `      <source url="${escapeXmlAttribute(item.source.url)}">${escapeXml(normalizeCharacters(item.source.title))}</source>`;
+	}
+
+	return `    <item>
+      <title>${title}</title>
+      <link>${escapeXmlAttribute(item.link)}</link>
+      <guid isPermaLink="true">${escapeXmlAttribute(guid)}</guid>
+      <pubDate>${pubDate}</pubDate>${description ? `\n      <description>${description}</description>` : ''}${content ? `\n      <content:encoded><![CDATA[${content}]]></content:encoded>` : ''}${author ? `\n      <author>${author}</author>` : ''}${item.comments ? `\n      <comments>${escapeXmlAttribute(item.comments)}</comments>` : ''}${categories ? `\n${categories}` : ''}${enclosure ? `\n${enclosure}` : ''}${source ? `\n${source}` : ''}
+    </item>`;
+}
+
+export function generateRSSFeed(config: RSSChannelConfig, items: RSSItem[]): string {
+	const language = config.language || 'en';
+	const generator = config.generator || 'SvelteKit with AT Protocol';
+	const lastBuildDate = formatRSSDate(new Date());
+	const title = escapeXml(normalizeCharacters(config.title));
+	const link = escapeXmlAttribute(config.link);
+	const description = escapeXml(normalizeCharacters(config.description));
+	const generatorText = escapeXml(normalizeCharacters(generator));
+
+	const atomLink = config.selfLink
+		? `    <atom:link href="${escapeXmlAttribute(config.selfLink)}" rel="self" type="application/rss+xml" />`
+		: '';
+
+	const optionalFields = [];
+	if (config.copyright)
+		optionalFields.push(
+			`    <copyright>${escapeXml(normalizeCharacters(config.copyright))}</copyright>`
+		);
+	if (config.managingEditor)
+		optionalFields.push(
+			`    <managingEditor>${escapeXml(normalizeCharacters(config.managingEditor))}</managingEditor>`
+		);
+	if (config.webMaster)
+		optionalFields.push(
+			`    <webMaster>${escapeXml(normalizeCharacters(config.webMaster))}</webMaster>`
+		);
+	if (config.ttl) optionalFields.push(`    <ttl>${config.ttl}</ttl>`);
+
+	const itemsXml = items.map((item) => generateRSSItem(item)).join('\n');
+
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">
+  <channel>
+    <title>${title}</title>
+    <link>${link}</link>
+    <description>${description}</description>
+    <language>${language}</language>${atomLink ? `\n${atomLink}` : ''}
+    <lastBuildDate>${lastBuildDate}</lastBuildDate>
+    <generator>${generatorText}</generator>${optionalFields.length > 0 ? `\n${optionalFields.join('\n')}` : ''}
+${itemsXml}
+  </channel>
+</rss>`;
+}
+
+export function createRSSResponse(
+	feed: string,
+	options?: { cacheMaxAge?: number; status?: number }
+): Response {
+	const cacheMaxAge = options?.cacheMaxAge ?? 3600;
+	const status = options?.status ?? 200;
+	return new Response(feed, {
+		status,
+		headers: {
+			'Content-Type': 'application/rss+xml; charset=utf-8',
+			'Cache-Control': `public, max-age=${cacheMaxAge}`
+		}
+	});
+}

package/src/url.ts

@@ -0,0 +1,29 @@
+export function getDomain(url: string): string {
+	try {
+		const urlObj = new URL(url);
+		return urlObj.hostname.replace('www.', '');
+	} catch {
+		return '';
+	}
+}
+
+export function atUriToBlueskyUrl(uri: string): string {
+	const parts = uri.split('/');
+	const did = parts[2];
+	const rkey = parts[4];
+	return `https://witchsky.app/profile/${did}/post/${rkey}`;
+}
+
+export function getBlueskyProfileUrl(actor: string): string {
+	return `https://witchsky.app/profile/${actor}`;
+}
+
+export function isExternalUrl(url: string): boolean {
+	if (typeof window === 'undefined') return true;
+	try {
+		const urlObj = new URL(url, window.location.href);
+		return urlObj.origin !== window.location.origin;
+	} catch {
+		return false;
+	}
+}

package/src/validators.ts

@@ -0,0 +1,59 @@
+export function isValidTid(tid: string): boolean {
+	const tidPattern = /^[a-zA-Z0-9]{12,16}$/;
+	return tidPattern.test(tid);
+}
+
+export function isValidDid(did: string): boolean {
+	const didPattern = /^did:[a-z]+:[a-zA-Z0-9._:-]+$/;
+	return didPattern.test(did);
+}
+
+export function truncateText(text: string, maxLength: number, ellipsis = '...'): string {
+	if (text.length <= maxLength) return text;
+	return text.slice(0, maxLength - ellipsis.length).trim() + ellipsis;
+}
+
+export function escapeHtml(text: string): string {
+	const div = typeof document !== 'undefined' ? document.createElement('div') : null;
+	if (div) {
+		div.textContent = text;
+		return div.innerHTML;
+	}
+	return text
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#039;');
+}
+
+export function getInitials(name: string): string {
+	const words = name.trim().split(/\s+/);
+	if (words.length === 1) return words[0].charAt(0).toUpperCase();
+	return (words[0].charAt(0) + words[words.length - 1].charAt(0)).toUpperCase();
+}
+
+export function debounce<T extends (...args: any[]) => any>(
+	func: T,
+	delay: number
+): (...args: Parameters<T>) => void {
+	let timeoutId: ReturnType<typeof setTimeout>;
+	return (...args: Parameters<T>) => {
+		clearTimeout(timeoutId);
+		timeoutId = setTimeout(() => func(...args), delay);
+	};
+}
+
+export function throttle<T extends (...args: any[]) => any>(
+	func: T,
+	limit: number
+): (...args: Parameters<T>) => void {
+	let inThrottle: boolean;
+	return (...args: Parameters<T>) => {
+		if (!inThrottle) {
+			func(...args);
+			inThrottle = true;
+			setTimeout(() => (inThrottle = false), limit);
+		}
+	};
+}