@regardio/js 0.5.0 → 0.7.0

package/LICENSE

@@ -1,6 +1,6 @@
 # The MIT License (MIT)
 
-Copyright © 2025 Regardio
+Copyright © 2026 Regardio
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/dist/assert/index.d.mts

@@ -0,0 +1,45 @@
+//#region src/assert/invariant.d.ts
+/**
+* Provide a condition and if that condition is falsey, this throws an error
+* with the given message.
+*
+* inspired by invariant from 'tiny-invariant' except will still include the
+* message in production.
+*
+* @example
+* invariant(typeof value === 'string', `value must be a string`)
+*
+* @param condition The condition to check
+* @param message The message to throw (or a callback to generate the message)
+*
+* @throws {Error} if condition is falsey
+*/
+declare function invariant(condition: unknown, message: string | (() => string)): asserts condition;
+/**
+* Provide a condition and if that condition is falsey, this throws a 400
+* Response with the given message.
+*
+* inspired by invariant from 'tiny-invariant'
+*
+* @example
+* invariantResponse(typeof value === 'string', `value must be a string`)
+*
+* @param condition The condition to check
+* @param message The message to throw (or a callback to generate the message)
+* @param responseInit Additional response init options if a response is thrown
+*
+* @throws {Response} if condition is falsey
+*/
+declare function invariantResponse(condition: unknown, message: string | (() => string), responseInit?: ResponseInit): asserts condition;
+//#endregion
+//#region src/assert/verify-file-accept.d.ts
+/**
+* Check if a mime type matches the set given in accept
+*
+* @param type the mime type to test, ex image/png
+* @param accept the mime types to accept, ex audio/*,video/*,image/png
+* @returns true if the mime is accepted, false otherwise
+*/
+declare function verifyAccept(type: string, accept: string): boolean;
+//#endregion
+export { invariant, invariantResponse, verifyAccept };

package/dist/assert/index.mjs

@@ -0,0 +1,57 @@
+//#region src/assert/invariant.ts
+/**
+* Provide a condition and if that condition is falsey, this throws an error
+* with the given message.
+*
+* inspired by invariant from 'tiny-invariant' except will still include the
+* message in production.
+*
+* @example
+* invariant(typeof value === 'string', `value must be a string`)
+*
+* @param condition The condition to check
+* @param message The message to throw (or a callback to generate the message)
+*
+* @throws {Error} if condition is falsey
+*/
+function invariant(condition, message) {
+	if (!condition) throw new Error(typeof message === "function" ? message() : message);
+}
+/**
+* Provide a condition and if that condition is falsey, this throws a 400
+* Response with the given message.
+*
+* inspired by invariant from 'tiny-invariant'
+*
+* @example
+* invariantResponse(typeof value === 'string', `value must be a string`)
+*
+* @param condition The condition to check
+* @param message The message to throw (or a callback to generate the message)
+* @param responseInit Additional response init options if a response is thrown
+*
+* @throws {Response} if condition is falsey
+*/
+function invariantResponse(condition, message, responseInit) {
+	if (!condition) throw new Response(typeof message === "function" ? message() : message, {
+		status: 400,
+		...responseInit
+	});
+}
+
+//#endregion
+//#region src/assert/verify-file-accept.ts
+/**
+* Check if a mime type matches the set given in accept
+*
+* @param type the mime type to test, ex image/png
+* @param accept the mime types to accept, ex audio/*,video/*,image/png
+* @returns true if the mime is accepted, false otherwise
+*/
+function verifyAccept(type, accept) {
+	const allowed = accept.split(",").map((x) => x.trim());
+	return allowed.includes(type) || allowed.includes(`${type.split("/")[0]}/*`);
+}
+
+//#endregion
+export { invariant, invariantResponse, verifyAccept };

package/dist/encoding/index.d.mts

@@ -0,0 +1,14 @@
+//#region src/encoding/base64.d.ts
+/**
+* Converts a base64 string to a Uint8Array
+* @param base64String The base64 string to convert
+* @returns A Uint8Array containing the decoded data
+*/
+declare const urlBase64ToUint8Array: (base64String: string) => Uint8Array;
+/**
+* Generate a cryptographically secure random base64 string.
+* @returns A base64-encoded random string (16 bytes of entropy)
+*/
+declare function generateRandomBase64(): string;
+//#endregion
+export { generateRandomBase64, urlBase64ToUint8Array };

package/dist/encoding/index.mjs

@@ -0,0 +1,25 @@
+//#region src/encoding/base64.ts
+/**
+* Converts a base64 string to a Uint8Array
+* @param base64String The base64 string to convert
+* @returns A Uint8Array containing the decoded data
+*/
+const urlBase64ToUint8Array = (base64String) => {
+	const base64 = (base64String + "=".repeat((4 - base64String.length % 4) % 4)).replace(/-/g, "+").replace(/_/g, "/");
+	const rawData = window.atob(base64);
+	const outputArray = new Uint8Array(rawData.length);
+	for (let i = 0; i < rawData.length; ++i) outputArray[i] = rawData.charCodeAt(i);
+	return outputArray;
+};
+/**
+* Generate a cryptographically secure random base64 string.
+* @returns A base64-encoded random string (16 bytes of entropy)
+*/
+function generateRandomBase64() {
+	const array = new Uint8Array(16);
+	crypto.getRandomValues(array);
+	return btoa(String.fromCharCode(...array));
+}
+
+//#endregion
+export { generateRandomBase64, urlBase64ToUint8Array };

package/dist/http/index.d.mts

@@ -0,0 +1,53 @@
+//#region src/http/cookie.d.ts
+/**
+* Helper function to set cookies in a more controlled way
+* @param name - The name of the cookie
+* @param value - The value to set
+* @param options - Cookie options
+*/
+declare function setCookieValue(name: string, value: string, options?: {
+  expires?: Date;
+  path?: string;
+  sameSite?: string;
+  secure?: boolean;
+  domain?: string;
+}): void;
+/**
+* Get a cookie value by name
+* @param name - The name of the cookie to get
+* @returns The cookie value or null if not found
+*/
+declare function getCookieValue(name: string): string | null;
+//#endregion
+//#region src/http/domain.d.ts
+/**
+* Helper utility used to extract the domain from the request even if it's
+* behind a proxy. This is useful for sitemaps and other things.
+* @param request Request object
+* @returns Current domain
+*/
+declare const createDomain: (request: Request) => string;
+//#endregion
+//#region src/http/is-route-active.d.ts
+/**
+* @name isRouteActive
+* @description A function to check if a route is active. This is used to
+* @param end
+* @param path
+* @param currentPath
+*/
+declare function isRouteActive(path: string, currentPath: string, end?: boolean | ((path: string) => boolean) | undefined): boolean;
+/**
+* @name checkIfRouteIsActive
+* @description A function to check if a route is active. This is used to
+* highlight the active link in the navigation.
+* @param targetLink - The link to check against
+* @param currentRoute - the current route
+* @param depth - how far down should segments be matched?
+*/
+declare function checkIfRouteIsActive(targetLink: string, currentRoute: string, depth?: number): boolean;
+//#endregion
+//#region src/http/request-helpers.d.ts
+declare function getCleanUrl(request: Request): string;
+//#endregion
+export { checkIfRouteIsActive, createDomain, getCleanUrl, getCookieValue, isRouteActive, setCookieValue };

package/dist/http/index.mjs

@@ -0,0 +1,122 @@
+//#region src/http/cookie.ts
+/**
+* Helper function to set cookies in a more controlled way
+* @param name - The name of the cookie
+* @param value - The value to set
+* @param options - Cookie options
+*/
+function setCookieValue(name, value, options = {}) {
+	if (typeof window === "undefined") {
+		console.warn("Cannot set cookie on server side");
+		return;
+	}
+	let cookieString = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+	if (options.expires) cookieString += `; expires=${options.expires.toUTCString()}`;
+	if (options.path) cookieString += `; path=${options.path}`;
+	if (options.sameSite) cookieString += `; SameSite=${options.sameSite}`;
+	if (options.secure) cookieString += "; Secure";
+	if (options.domain) cookieString += `; domain=${options.domain}`;
+	try {
+		document.cookie = cookieString;
+	} catch (error) {
+		if (error instanceof Error) console.error(`Failed to set cookie '${name}':`, error.message);
+		else console.error(`Failed to set cookie '${name}': Unknown error`);
+	}
+}
+/**
+* Get a cookie value by name
+* @param name - The name of the cookie to get
+* @returns The cookie value or null if not found
+*/
+function getCookieValue(name) {
+	if (typeof window === "undefined") {
+		console.warn("Cannot get cookie on server side");
+		return null;
+	}
+	const parts = `; ${document.cookie}`.split(`; ${name}=`);
+	if (parts.length === 2) {
+		const cookieValue = parts.pop()?.split(";").shift();
+		return cookieValue ? decodeURIComponent(cookieValue) : null;
+	}
+	return null;
+}
+
+//#endregion
+//#region src/http/domain.ts
+/**
+* Helper utility used to extract the domain from the request even if it's
+* behind a proxy. This is useful for sitemaps and other things.
+* @param request Request object
+* @returns Current domain
+*/
+const createDomain = (request) => {
+	const headers = request.headers;
+	const maybeProto = headers.get("x-forwarded-proto");
+	const maybeHost = headers.get("host");
+	const url = new URL(request.url);
+	if (maybeProto) return `${maybeProto}://${maybeHost ?? url.host}`;
+	if (url.hostname === "localhost") return `http://${url.host}`;
+	return `https://${url.host}`;
+};
+
+//#endregion
+//#region src/http/is-route-active.ts
+const ROOT_PATH = "/";
+/**
+* @name isRouteActive
+* @description A function to check if a route is active. This is used to
+* @param end
+* @param path
+* @param currentPath
+*/
+function isRouteActive(path, currentPath, end) {
+	if (path === currentPath) return true;
+	if (typeof end === "function") return !end(currentPath);
+	return checkIfRouteIsActive(path, currentPath, end ?? true ? 1 : 3);
+}
+/**
+* @name checkIfRouteIsActive
+* @description A function to check if a route is active. This is used to
+* highlight the active link in the navigation.
+* @param targetLink - The link to check against
+* @param currentRoute - the current route
+* @param depth - how far down should segments be matched?
+*/
+function checkIfRouteIsActive(targetLink, currentRoute, depth = 1) {
+	const currentRoutePath = currentRoute.split("?")[0] ?? "";
+	if (!isRoot(currentRoutePath) && isRoot(targetLink)) return false;
+	if (!currentRoutePath.includes(targetLink)) return false;
+	if (targetLink === currentRoutePath) return true;
+	return hasMatchingSegments(targetLink, currentRoutePath, depth);
+}
+function splitIntoSegments(href) {
+	return href.split("/").filter(Boolean);
+}
+function hasMatchingSegments(targetLink, currentRoute, depth) {
+	const segments = splitIntoSegments(targetLink);
+	const matchingSegments = numberOfMatchingSegments(currentRoute, segments);
+	if (targetLink === currentRoute) return true;
+	return matchingSegments > segments.length - (depth - 1);
+}
+function numberOfMatchingSegments(href, segments) {
+	let count = 0;
+	for (const segment of splitIntoSegments(href)) if (segments.includes(segment)) count += 1;
+	else return count;
+	return count;
+}
+function isRoot(path) {
+	return path === ROOT_PATH;
+}
+
+//#endregion
+//#region src/http/request-helpers.ts
+function getCleanUrl(request) {
+	const url = new URL(request.url);
+	url.searchParams.forEach((_, key) => {
+		url.searchParams.delete(key);
+	});
+	return url.toString();
+}
+
+//#endregion
+export { checkIfRouteIsActive, createDomain, getCleanUrl, getCookieValue, isRouteActive, setCookieValue };

package/dist/intl/index.d.mts

@@ -0,0 +1,92 @@
+import { Cookie, SessionStorage } from "react-router";
+
+//#region src/intl/language-detector.d.ts
+interface LanguageDetectorOption {
+  /**
+  * Define the list of supported languages, this is used to determine if one of
+  * the languages requested by the user is supported by the application.
+  * This should be be same as the supportedLngs in the i18next options.
+  */
+  supportedLanguages: string[];
+  /**
+  * Define the fallback language that it's going to be used in the case user
+  * expected language is not supported.
+  * This should be be same as the fallbackLng in the i18next options.
+  */
+  fallbackLanguage: string;
+  /**
+  * If you want to use a cookie to store the user preferred language, you can
+  * pass the Cookie object here.
+  */
+  cookie?: Cookie;
+  /**
+  * If you want to use a session to store the user preferred language, you can
+  * pass the SessionStorage object here.
+  * When this is not defined, getting the locale will ignore the session.
+  */
+  sessionStorage?: SessionStorage;
+  /**
+  * If defined a sessionStorage and want to change the default key used to
+  * store the user preferred language, you can pass the key here.
+  * @default "lng"
+  */
+  sessionKey?: string;
+  /**
+  * If you want to use search parameters for language detection and want to
+  * change the default key used to for the parameter name,
+  * you can pass the key here.
+  * @default "lng"
+  */
+  searchParamKey?: string;
+  /**
+  * The order the library will use to detect the user preferred language.
+  * By default the order is
+  * - urlPath (first segment like /de/ or /en/)
+  * - cookie
+  * - session
+  * - searchParams
+  * - header
+  * And finally the fallback language.
+  */
+  order?: Array<"urlPath" | "searchParams" | "cookie" | "session" | "header">;
+}
+interface LanguageDetectorLinguiOptions {
+  detection: LanguageDetectorOption;
+}
+declare class LanguageDetectorLingui {
+  private detector;
+  private options;
+  constructor(options: LanguageDetectorLinguiOptions);
+  /**
+  * Detect the current locale by following the order defined in the
+  * `detection.order` option.
+  * By default the order is
+  * - urlPath (first segment like /de/ or /en/)
+  * - cookie
+  * - session
+  * - searchParams
+  * - header
+  * And finally the fallback language.
+  */
+  getLocale(request: Request): Promise<string>;
+}
+/**
+* The LanguageDetector contains the logic to detect the user preferred language
+* fully server-side by using a SessionStorage, Cookie, URLSearchParams, or
+* Headers.
+*/
+declare class LanguageDetector {
+  private options;
+  constructor(options: LanguageDetectorOption);
+  detect(request: Request): Promise<string>;
+  private isSessionOnly;
+  private isCookieOnly;
+  private fromUrlPath;
+  private fromSearchParams;
+  private fromCookie;
+  private fromSessionStorage;
+  private fromHeader;
+  private fromSupported;
+}
+//#endregion
+export { LanguageDetector, LanguageDetectorLingui, type LanguageDetectorLinguiOptions, type LanguageDetectorOption };

package/dist/intl/index.mjs

@@ -0,0 +1,124 @@
+import { parseAcceptLanguage } from "intl-parse-accept-language";
+
+//#region src/intl/language-detector.ts
+var LanguageDetectorLingui = class {
+	detector;
+	options;
+	constructor(options) {
+		this.options = options;
+		this.detector = new LanguageDetector(this.options.detection);
+	}
+	/**
+	* Detect the current locale by following the order defined in the
+	* `detection.order` option.
+	* By default the order is
+	* - urlPath (first segment like /de/ or /en/)
+	* - cookie
+	* - session
+	* - searchParams
+	* - header
+	* And finally the fallback language.
+	*/
+	async getLocale(request) {
+		return await this.detector.detect(request);
+	}
+};
+/**
+* The LanguageDetector contains the logic to detect the user preferred language
+* fully server-side by using a SessionStorage, Cookie, URLSearchParams, or
+* Headers.
+*/
+var LanguageDetector = class {
+	options;
+	constructor(options) {
+		this.options = options;
+		this.isSessionOnly(this.options);
+		this.isCookieOnly(this.options);
+	}
+	async detect(request) {
+		const order = this.options.order ?? [
+			"urlPath",
+			"cookie",
+			"session",
+			"searchParams",
+			"header"
+		];
+		for (const method of order) {
+			let locale = null;
+			if (method === "urlPath") locale = this.fromUrlPath(request);
+			if (method === "searchParams") locale = this.fromSearchParams(request);
+			if (method === "cookie") locale = await this.fromCookie(request);
+			if (method === "session") locale = await this.fromSessionStorage(request);
+			if (method === "header") locale = this.fromHeader(request);
+			if (locale) return locale;
+		}
+		return this.options.fallbackLanguage;
+	}
+	isSessionOnly(options) {
+		if (options.order?.length === 1 && options.order[0] === "session" && !options.sessionStorage) throw new Error("You need a sessionStorage if you want to only get the locale from the session");
+	}
+	isCookieOnly(options) {
+		if (options.order?.length === 1 && options.order[0] === "cookie" && !options.cookie) throw new Error("You need a cookie if you want to only get the locale from the cookie");
+	}
+	fromUrlPath(request) {
+		const pathSegments = new URL(request.url).pathname.split("/").filter(Boolean);
+		if (pathSegments.length > 0) {
+			const firstSegment = pathSegments[0];
+			if (firstSegment) return this.fromSupported(firstSegment);
+		}
+		return null;
+	}
+	fromSearchParams(request) {
+		const url = new URL(request.url);
+		if (!url.searchParams.has(this.options.searchParamKey ?? "lng")) return null;
+		return this.fromSupported(url.searchParams.get(this.options.searchParamKey ?? "lng"));
+	}
+	async fromCookie(request) {
+		if (!this.options.cookie) return null;
+		const cookie = this.options.cookie;
+		try {
+			const lng = await cookie.parse(request.headers.get("Cookie"));
+			if (typeof lng !== "string" || !lng) return null;
+			return this.fromSupported(lng);
+		} catch (_error) {
+			return null;
+		}
+	}
+	async fromSessionStorage(request) {
+		if (!this.options.sessionStorage) return null;
+		const lng = (await this.options.sessionStorage.getSession(request.headers.get("Cookie"))).get(this.options.sessionKey ?? "lng");
+		if (!lng) return null;
+		return this.fromSupported(lng);
+	}
+	fromHeader(request) {
+		const locales = getClientLocales(request);
+		if (!locales) return null;
+		if (Array.isArray(locales)) return this.fromSupported(locales.join(","));
+		return this.fromSupported(locales);
+	}
+	fromSupported(language) {
+		if (!language) return this.options.fallbackLanguage;
+		return parseAcceptLanguage(Array.isArray(language) ? language.join(",") : language, {
+			ignoreWildcard: true,
+			validate: (locale) => this.options.supportedLanguages.includes(locale) ? locale : null
+		})[0] || this.options.fallbackLanguage;
+	}
+};
+function getClientLocales(requestOrHeaders) {
+	const acceptLanguage = getHeaders(requestOrHeaders).get("Accept-Language");
+	if (!acceptLanguage) return void 0;
+	const locales = parseAcceptLanguage(acceptLanguage, {
+		ignoreWildcard: true,
+		validate: Intl.DateTimeFormat.supportedLocalesOf
+	});
+	if (locales.length === 0) return void 0;
+	if (locales.length === 1) return locales[0];
+	return locales;
+}
+function getHeaders(requestOrHeaders) {
+	if (requestOrHeaders instanceof Request) return requestOrHeaders.headers;
+	return requestOrHeaders;
+}
+
+//#endregion
+export { LanguageDetector, LanguageDetectorLingui };

package/dist/text/index.d.mts

@@ -0,0 +1,48 @@
+//#region src/text/bytes.d.ts
+declare function formatBytes(bytes: number, decimals?: number): string;
+//#endregion
+//#region src/text/text.d.ts
+/**
+* Replace straight quotes with typographically correct quotes for the given locale.
+*
+* @param text - The text containing straight quotes
+* @param locale - The locale to use for quote style (e.g., 'en', 'de', 'fr')
+* @returns Text with typographic quotes
+*
+* @example
+* typographicQuotes('"Hello"', 'en') // → '"Hello"'
+* typographicQuotes('"Hello"', 'de') // → '„Hello"'
+* typographicQuotes('"Hello"', 'fr') // → '« Hello »'
+*/
+declare function typographicQuotes(text: string, locale: string): string;
+declare function toBoolean(value: string | boolean | null | undefined): boolean;
+/**
+* Replace ­ HTML entity with Unicode soft hyphen
+*/
+declare function replaceShyInString(input: string): string;
+/**
+* Split text into sentences
+*/
+declare function splitIntoSentences(text: string): string[];
+/**
+* Split text into words
+*/
+declare function splitIntoWords(text: string): string[];
+/**
+* Truncate text to a maximum length
+*/
+declare function truncateText(text: string, maxLength: number, suffix?: string): string;
+/**
+* Author info parsed from a string like "Name <email> (url)"
+*/
+type AuthorInfo = {
+  name?: string;
+  email?: string;
+  url?: string;
+};
+/**
+* Parse an author string in the format "Name <email> (url)"
+*/
+declare function parseAuthorString(input: string): AuthorInfo;
+//#endregion
+export { type AuthorInfo, formatBytes, parseAuthorString, replaceShyInString, splitIntoSentences, splitIntoWords, toBoolean, truncateText, typographicQuotes };