@regardio/js 0.2.3 → 0.3.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/intl/language-detector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"language-detector.d.ts","sourceRoot":"","sources":["../../src/intl/language-detector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG3D,MAAM,WAAW,sBAAsB;IAMrC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAM7B,gBAAgB,EAAE,MAAM,CAAC;IAKzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAMhB,cAAc,CAAC,EAAE,cAAc,CAAC;IAMhC,UAAU,CAAC,EAAE,MAAM,CAAC;IAOpB,cAAc,CAAC,EAAE,MAAM,CAAC;IAWxB,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,sBAAsB,CAAC;CACnC;AAED,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,OAAO,CAAgC;gBAEnC,OAAO,EAAE,6BAA6B;IAgBrC,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;CAG1D;AAOD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAAyB;gBAE5B,OAAO,EAAE,sBAAsB;IAM9B,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAgCtD,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,gBAAgB;YAQV,UAAU;YAcV,kBAAkB;IAYhC,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,aAAa;CAYtB"}
+{"version":3,"file":"language-detector.d.ts","sourceRoot":"","sources":["../../src/intl/language-detector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,WAAW,sBAAsB;IAMrC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAM7B,gBAAgB,EAAE,MAAM,CAAC;IAKzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAMhB,cAAc,CAAC,EAAE,cAAc,CAAC;IAMhC,UAAU,CAAC,EAAE,MAAM,CAAC;IAOpB,cAAc,CAAC,EAAE,MAAM,CAAC;IAWxB,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,sBAAsB,CAAC;CACnC;AAED,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,OAAO,CAAgC;gBAEnC,OAAO,EAAE,6BAA6B;IAgBrC,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;CAG1D;AAOD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAAyB;gBAE5B,OAAO,EAAE,sBAAsB;IAM9B,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAgCtD,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,gBAAgB;YAQV,UAAU;YAcV,kBAAkB;IAYhC,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,aAAa;CAYtB"}

package/dist/intl/language-detector.js

@@ -1,5 +1,4 @@
 import { parseAcceptLanguage } from 'intl-parse-accept-language';
-import { getClientLocales } from './locale';
 export class LanguageDetectorLingui {
     detector;
     options;
@@ -112,3 +111,24 @@ export class LanguageDetector {
         return parsed[0] || this.options.fallbackLanguage;
     }
 }
+function getClientLocales(requestOrHeaders) {
+    const headers = getHeaders(requestOrHeaders);
+    const acceptLanguage = headers.get('Accept-Language');
+    if (!acceptLanguage)
+        return undefined;
+    const locales = parseAcceptLanguage(acceptLanguage, {
+        ignoreWildcard: true,
+        validate: Intl.DateTimeFormat.supportedLocalesOf,
+    });
+    if (locales.length === 0)
+        return undefined;
+    if (locales.length === 1)
+        return locales[0];
+    return locales;
+}
+function getHeaders(requestOrHeaders) {
+    if (requestOrHeaders instanceof Request) {
+        return requestOrHeaders.headers;
+    }
+    return requestOrHeaders;
+}

package/package.json

@@ -48,10 +48,6 @@
       "import": "./dist/intl/language-detector.js",
       "types": "./dist/intl/language-detector.d.ts"
     },
-    "./intl/locale": {
-      "import": "./dist/intl/locale.js",
-      "types": "./dist/intl/locale.d.ts"
-    },
     "./time/time": {
       "import": "./dist/time/time.js",
       "types": "./dist/time/time.d.ts"
@@ -108,5 +104,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.2.3"
+  "version": "0.3.0"
 }

package/dist/intl/locale.d.ts

@@ -1,4 +0,0 @@
-export type Locales = string | string[] | undefined;
-export declare function getClientLocales(headers: Headers): Locales;
-export declare function getClientLocales(request: Request): Locales;
-//# sourceMappingURL=locale.d.ts.map

package/dist/intl/locale.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../src/intl/locale.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;AAiBpD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;AAC5D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC"}

package/dist/intl/locale.js

@@ -1,22 +0,0 @@
-import { parseAcceptLanguage } from 'intl-parse-accept-language';
-export function getClientLocales(requestOrHeaders) {
-    const headers = getHeaders(requestOrHeaders);
-    const acceptLanguage = headers.get('Accept-Language');
-    if (!acceptLanguage)
-        return undefined;
-    const locales = parseAcceptLanguage(acceptLanguage, {
-        ignoreWildcard: true,
-        validate: Intl.DateTimeFormat.supportedLocalesOf,
-    });
-    if (locales.length === 0)
-        return undefined;
-    if (locales.length === 1)
-        return locales[0];
-    return locales;
-}
-function getHeaders(requestOrHeaders) {
-    if (requestOrHeaders instanceof Request) {
-        return requestOrHeaders.headers;
-    }
-    return requestOrHeaders;
-}

package/dist/intl/locale.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=locale.test.d.ts.map

package/dist/intl/locale.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"locale.test.d.ts","sourceRoot":"","sources":["../../src/intl/locale.test.ts"],"names":[],"mappings":""}

package/dist/intl/locale.test.js

@@ -1,75 +0,0 @@
-import { describe, expect, test } from 'vitest';
-import { getClientLocales } from './locale';
-describe('getClientLocales', () => {
-    describe('with Request object', () => {
-        test('should return undefined when Accept-Language header is missing', () => {
-            const request = new Request('https://example.com');
-            expect(getClientLocales(request)).toBeUndefined();
-        });
-        test('should return single locale when only one is provided', () => {
-            const request = new Request('https://example.com', {
-                headers: { 'Accept-Language': 'en-US' },
-            });
-            expect(getClientLocales(request)).toBe('en-US');
-        });
-        test('should return array of locales sorted by quality', () => {
-            const request = new Request('https://example.com', {
-                headers: { 'Accept-Language': 'en-US,de;q=0.9,fr;q=0.8' },
-            });
-            const result = getClientLocales(request);
-            expect(Array.isArray(result)).toBe(true);
-            expect(result).toContain('en-US');
-            expect(result).toContain('de');
-        });
-        test('should return undefined for invalid locales', () => {
-            const request = new Request('https://example.com', {
-                headers: { 'Accept-Language': 'invalid-locale-xyz' },
-            });
-            expect(getClientLocales(request)).toBeUndefined();
-        });
-        test('should ignore wildcard (*)', () => {
-            const request = new Request('https://example.com', {
-                headers: { 'Accept-Language': '*' },
-            });
-            expect(getClientLocales(request)).toBeUndefined();
-        });
-    });
-    describe('with Headers object', () => {
-        test('should return undefined when Accept-Language header is missing', () => {
-            const headers = new Headers();
-            expect(getClientLocales(headers)).toBeUndefined();
-        });
-        test('should return single locale when only one is provided', () => {
-            const headers = new Headers({ 'Accept-Language': 'de-DE' });
-            expect(getClientLocales(headers)).toBe('de-DE');
-        });
-        test('should return array of locales sorted by quality', () => {
-            const headers = new Headers({ 'Accept-Language': 'fr-FR,en;q=0.9,de;q=0.8' });
-            const result = getClientLocales(headers);
-            expect(Array.isArray(result)).toBe(true);
-            expect(result).toContain('fr-FR');
-        });
-    });
-    describe('quality value handling', () => {
-        test('should prioritize higher quality values', () => {
-            const request = new Request('https://example.com', {
-                headers: { 'Accept-Language': 'de;q=0.5,en;q=0.9' },
-            });
-            const result = getClientLocales(request);
-            expect(Array.isArray(result)).toBe(true);
-            if (Array.isArray(result)) {
-                expect(result[0]).toBe('en');
-            }
-        });
-        test('should handle locales without explicit quality (default q=1)', () => {
-            const request = new Request('https://example.com', {
-                headers: { 'Accept-Language': 'en,de;q=0.9' },
-            });
-            const result = getClientLocales(request);
-            expect(Array.isArray(result)).toBe(true);
-            if (Array.isArray(result)) {
-                expect(result[0]).toBe('en');
-            }
-        });
-    });
-});