@regardio/js 0.2.4 → 0.4.0

package/README.md

@@ -5,12 +5,33 @@
 A collection of lightweight, tree-shakeable utility functions for common tasks
 like 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 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
 ```
 
+## Documentation
+
+See the [docs](./docs) folder for detailed documentation on each module.
+
 ## Modules
 
 ### async/delay
@@ -146,9 +167,34 @@ verifyAccept('image/png', 'image/*'); // true
 verifyAccept('video/mp4', 'image/*'); // false
 ```
 
+## Module Overview
+
+| Module | Description |
+|--------|-------------|
+| `async/delay` | Promise-based delay utility |
+| `browser/base64` | URL-safe base64 to Uint8Array conversion |
+| `format/bytes` | Human-readable byte formatting |
+| `format/measure` | Performance measurement with logging |
+| `http/cookie` | Browser cookie get/set helpers |
+| `http/domain` | Domain extraction from requests (proxy-aware) |
+| `http/request-helpers` | URL cleaning utilities |
+| `intl/language-detector` | Server-side language detection for i18n |
+| `intl/locale` | Client locale extraction from headers |
+| `time/time` | Time formatting and date utilities |
+| `validation/invariant` | Runtime assertion utilities |
+| `validation/verify-file-accept` | MIME type validation for file uploads |
+
+## 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.
+**MIT License** — Free to use in commercial and open source projects.
 
 ---
 

package/dist/async/delay.d.ts

@@ -1,2 +1,7 @@
-export declare function delay(ms: number): Promise<unknown>;
-//# sourceMappingURL=delay.d.ts.map
+/** Delays using a promise
+ * @param ms Milisecods of delay
+ * @return Promise
+ */
+declare function delay(ms: number): Promise<unknown>;
+
+export { delay };

package/dist/async/delay.js

@@ -1,5 +1,8 @@
-export function delay(ms) {
-    return new Promise((resolve) => {
-        return setTimeout(resolve, ms);
-    });
+// src/async/delay.ts
+function delay(ms) {
+  return new Promise((resolve) => {
+    return setTimeout(resolve, ms);
+  });
 }
+
+export { delay };

package/dist/browser/base64.d.ts

@@ -1,2 +1,8 @@
-export declare const urlBase64ToUint8Array: (base64String: string) => Uint8Array;
-//# sourceMappingURL=base64.d.ts.map
+/**
+ * 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;
+
+export { urlBase64ToUint8Array };

package/dist/browser/base64.js

@@ -1,10 +1,13 @@
-export const urlBase64ToUint8Array = (base64String) => {
-    const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
-    const base64 = (base64String + padding).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;
+// src/browser/base64.ts
+var urlBase64ToUint8Array = (base64String) => {
+  const padding = "=".repeat((4 - base64String.length % 4) % 4);
+  const base64 = (base64String + padding).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;
 };
+
+export { urlBase64ToUint8Array };

package/dist/format/bytes.d.ts

@@ -1,2 +1,3 @@
-export declare function formatBytes(bytes: number, decimals?: number): string;
-//# sourceMappingURL=bytes.d.ts.map
+declare function formatBytes(bytes: number, decimals?: number): string;
+
+export { formatBytes };

package/dist/format/bytes.js

@@ -1,10 +1,13 @@
-export function formatBytes(bytes, decimals = 2) {
-    if (!+bytes) {
-        return '0 Bytes';
-    }
-    const k = 1000;
-    const dm = decimals < 0 ? 0 : decimals;
-    const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
-    const i = Math.floor(Math.log(bytes) / Math.log(k));
-    return `${Number.parseFloat((bytes / k ** i).toFixed(dm))} ${sizes[i]}`;
+// src/format/bytes.ts
+function formatBytes(bytes, decimals = 2) {
+  if (!+bytes) {
+    return "0 Bytes";
+  }
+  const k = 1e3;
+  const dm = decimals < 0 ? 0 : decimals;
+  const sizes = ["Bytes", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${Number.parseFloat((bytes / k ** i).toFixed(dm))} ${sizes[i]}`;
 }
+
+export { formatBytes };

package/dist/format/measure.d.ts

@@ -1,2 +1,3 @@
-export declare function measure<Result>(key: string, callback: () => Result | Promise<Result>): Promise<Result>;
-//# sourceMappingURL=measure.d.ts.map
+declare function measure<Result>(key: string, callback: () => Result | Promise<Result>): Promise<Result>;
+
+export { measure };

package/dist/format/measure.js

@@ -1,14 +1,16 @@
-export async function measure(key, callback) {
-    const start = Date.now();
-    try {
-        let result = callback();
-        if (result instanceof Promise) {
-            result = await result;
-        }
-        return result;
-    }
-    finally {
-        const end = Date.now();
-        console.log(`${key} took ${end - start}ms`);
+// src/format/measure.ts
+async function measure(key, callback) {
+  const start = Date.now();
+  try {
+    let result = callback();
+    if (result instanceof Promise) {
+      result = await result;
     }
+    return result;
+  } finally {
+    const end = Date.now();
+    console.log(`${key} took ${end - start}ms`);
+  }
 }
+
+export { measure };

package/dist/http/cookie.d.ts

@@ -1,9 +1,21 @@
-export declare function setCookieValue(name: string, value: string, options?: {
+/**
+ * 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;
-export declare function getCookieValue(name: string): string | null;
-//# sourceMappingURL=cookie.d.ts.map
+/**
+ * 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;
+
+export { getCookieValue, setCookieValue };

package/dist/http/cookie.js

@@ -1,46 +1,47 @@
-export 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`);
-        }
-    }
+// src/http/cookie.ts
+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`);
+    }
+  }
 }
-export function getCookieValue(name) {
-    if (typeof window === 'undefined') {
-        console.warn('Cannot get cookie on server side');
-        return null;
-    }
-    const value = `; ${document.cookie}`;
-    const parts = value.split(`; ${name}=`);
-    if (parts.length === 2) {
-        const cookieValue = parts.pop()?.split(';').shift();
-        return cookieValue ? decodeURIComponent(cookieValue) : null;
-    }
+function getCookieValue(name) {
+  if (typeof window === "undefined") {
+    console.warn("Cannot get cookie on server side");
     return null;
+  }
+  const value = `; ${document.cookie}`;
+  const parts = value.split(`; ${name}=`);
+  if (parts.length === 2) {
+    const cookieValue = parts.pop()?.split(";").shift();
+    return cookieValue ? decodeURIComponent(cookieValue) : null;
+  }
+  return null;
 }
+
+export { getCookieValue, setCookieValue };

package/dist/http/domain.d.ts

@@ -1,2 +1,9 @@
-export declare const createDomain: (request: Request) => string;
-//# sourceMappingURL=domain.d.ts.map
+/**
+ * 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;
+
+export { createDomain };

package/dist/http/domain.js

@@ -1,13 +1,16 @@
-export 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}`;
+// src/http/domain.ts
+var 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}`;
 };
+
+export { createDomain };

package/dist/http/request-helpers.d.ts

@@ -1,2 +1,3 @@
-export declare function getCleanUrl(request: Request): string;
-//# sourceMappingURL=request-helpers.d.ts.map
+declare function getCleanUrl(request: Request): string;
+
+export { getCleanUrl };

package/dist/http/request-helpers.js

@@ -1,7 +1,10 @@
-export function getCleanUrl(request) {
-    const url = new URL(request.url);
-    url.searchParams.forEach((_, key) => {
-        url.searchParams.delete(key);
-    });
-    return url.toString();
+// 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();
 }
+
+export { getCleanUrl };

package/dist/intl/language-detector.d.ts

@@ -1,23 +1,80 @@
-import type { Cookie, SessionStorage } from 'react-router';
-export interface LanguageDetectorOption {
+import { Cookie, SessionStorage } from 'react-router';
+
+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'>;
 }
-export interface LanguageDetectorLinguiOptions {
+interface LanguageDetectorLinguiOptions {
     detection: LanguageDetectorOption;
 }
-export declare class LanguageDetectorLingui {
+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>;
 }
-export declare class LanguageDetector {
+/**
+ * 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>;
@@ -30,4 +87,5 @@ export declare class LanguageDetector {
     private fromHeader;
     private fromSupported;
 }
-//# sourceMappingURL=language-detector.d.ts.map
+
+export { LanguageDetector, LanguageDetectorLingui, type LanguageDetectorLinguiOptions, type LanguageDetectorOption };