@regardio/js 1.0.2 → 1.1.1

package/README.md

@@ -1,26 +1,25 @@
 # @regardio/js
 
-> **TypeScript utilities for Regardio applications**
+> 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.
+A collection of small, tree-shakeable utilities for the everyday work of text, HTTP, internationalisation, time, and validation — the pieces you end up re-implementing in every project.
 
-## ⚠️ Pre-release Notice
+## 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:
+This package is currently at v0.x. The utilities run in production across Regardio's own projects, but the API may still move between minor versions. A few habits that help:
 
-- Pinning to exact versions in your `package.json`
-- Reviewing changelogs before upgrading
-- Expecting potential breaking changes until v1.0
+- Pin to exact versions in `package.json`
+- Read the changelog before upgrading
+- Expect the occasional breaking change until v1.0
 
-## Why This Package?
+## What it's for
 
-We created `@regardio/js` to:
+`@regardio/js` exists so a handful of steady utilities don't have to be reinvented:
 
-- **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
+- **Shared, well-used helpers** — these functions carry real Regardio projects and have been refined through actual use
+- **Less boilerplate** — text formatting, cookie handling, language detection, and time formatting collected in one place
+- **Framework-agnostic** — works with any JavaScript/TypeScript project (React, Node, Deno, and so on)
+- **Tree-shakeable** — import what's needed, leave the rest out of the bundle
 
 ## Installation
 
@@ -30,9 +29,9 @@ pnpm add @regardio/js
 
 ## Modules
 
-### @regardio/js/text
+### `@regardio/js/text`
 
-String manipulation and formatting utilities.
+String manipulation and formatting.
 
 ```ts
 import {
@@ -49,9 +48,9 @@ formatBytes(1500000); // "1.5 MB"
 parseAuthorString('John <john@example.com>'); // { name: 'John', email: 'john@example.com' }
 ```
 
-### @regardio/js/time
+### `@regardio/js/time`
 
-Date, time, and async utilities.
+Date, time, and async helpers.
 
 ```ts
 import {
@@ -68,17 +67,17 @@ await delay(1000); // Wait 1 second
 await measure('fetchData', () => fetch('/api')); // Logs timing
 ```
 
-### @regardio/js/http
+### `@regardio/js/http`
 
 HTTP, cookie, and routing utilities.
 
 ```ts
 import {
-  // Client-side cookies (async - Cookie Store API + fallback)
+  // Client-side cookies (async — Cookie Store API + fallback)
   getCookie,
   setCookie,
   deleteCookie,
-  // Client-side cookies (sync - document.cookie only)
+  // Client-side cookies (sync — document.cookie only)
   getCookieSync,
   setCookieSync,
   deleteCookieSync,
@@ -121,7 +120,7 @@ const domain = createDomain(request); // "https://example.com"
 isRouteActive('/account', '/account/settings', false); // true
 ```
 
-### @regardio/js/intl
+### `@regardio/js/intl`
 
 Server-side language detection for i18n.
 
@@ -136,9 +135,9 @@ const detector = new LanguageDetector({
 const locale = await detector.detect(request);
 ```
 
-### @regardio/js/assert
+### `@regardio/js/assert`
 
-Runtime assertion and validation utilities.
+Runtime assertions and validation.
 
 ```ts
 import { invariant, invariantResponse, verifyAccept } from '@regardio/js/assert';
@@ -148,7 +147,7 @@ invariantResponse(user, 'User not found', { status: 404 }); // Throws Response
 verifyAccept('image/png', 'image/*'); // true
 ```
 
-### @regardio/js/encoding
+### `@regardio/js/encoding`
 
 Binary encoding utilities.
 
@@ -158,7 +157,7 @@ import { urlBase64ToUint8Array } from '@regardio/js/encoding';
 const bytes = urlBase64ToUint8Array(vapidPublicKey);
 ```
 
-## Module Overview
+## Module overview
 
 | Module | Description |
 |--------|-------------|
@@ -171,17 +170,16 @@ const bytes = urlBase64ToUint8Array(vapidPublicKey);
 
 ## Contributing
 
-This package is primarily maintained for Regardio's internal use, but we welcome:
+The package is maintained primarily for Regardio's own work, but contributions from elsewhere are welcome:
 
 - Bug reports and fixes
 - Documentation improvements
-- Feature suggestions (though we may not implement all requests)
+- Feature suggestions (not every one will become an implementation)
 
 ## License
 
-**MIT License** — Free to use in commercial and open source projects.
+**MIT** — free to use in commercial and open-source projects.
 
 ---
 
-*Part of the [Regardio Ensemble](https://regard.io/ensemble) toolkit for
-shared well-being.*
+*Part of the [Regardio Ensemble](https://regard.io/ensemble) toolkit for shared well-being.*

package/dist/intl/index.d.mts

@@ -1,5 +1,243 @@
-import { Cookie, SessionStorage } from "react-router";
-
+//#region ../../node_modules/.pnpm/cookie@1.1.1/node_modules/cookie/dist/index.d.ts
+/**
+ * Parse options.
+ */
+interface ParseOptions {
+  /**
+   * Specifies a function that will be used to decode a [cookie-value](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).
+   * Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to decode
+   * a previously-encoded cookie value into a JavaScript string.
+   *
+   * The default function is the global `decodeURIComponent`, wrapped in a `try..catch`. If an error
+   * is thrown it will return the cookie's original value. If you provide your own encode/decode
+   * scheme you must ensure errors are appropriately handled.
+   *
+   * @default decode
+   */
+  decode?: (str: string) => string | undefined;
+}
+interface StringifyOptions {
+  /**
+   * Specifies a function that will be used to encode a [cookie-value](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).
+   * Since value of a cookie has a limited character set (and must be a simple string), this function can be used to encode
+   * a value into a string suited for a cookie's value, and should mirror `decode` when parsing.
+   *
+   * @default encodeURIComponent
+   */
+  encode?: (str: string) => string;
+}
+/**
+ * Set-Cookie object.
+ */
+interface SetCookie {
+  /**
+   * Specifies the name of the cookie.
+   */
+  name: string;
+  /**
+   * Specifies the string to be the value for the cookie.
+   */
+  value: string | undefined;
+  /**
+   * Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.2).
+   *
+   * The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and
+   * `maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,
+   * so if both are set, they should point to the same date and time.
+   */
+  maxAge?: number;
+  /**
+   * Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.1).
+   * When no expiration is set, clients consider this a "non-persistent cookie" and delete it when the current session is over.
+   *
+   * The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and
+   * `maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,
+   * so if both are set, they should point to the same date and time.
+   */
+  expires?: Date;
+  /**
+   * Specifies the value for the [`Domain` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.3).
+   * When no domain is set, clients consider the cookie to apply to the current domain only.
+   */
+  domain?: string;
+  /**
+   * Specifies the value for the [`Path` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.4).
+   * When no path is set, the path is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4).
+   */
+  path?: string;
+  /**
+   * Enables the [`HttpOnly` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.6).
+   * When enabled, clients will not allow client-side JavaScript to see the cookie in `document.cookie`.
+   */
+  httpOnly?: boolean;
+  /**
+   * Enables the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5).
+   * When enabled, clients will only send the cookie back if the browser has an HTTPS connection.
+   */
+  secure?: boolean;
+  /**
+   * Enables the [`Partitioned` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-cutler-httpbis-partitioned-cookies/).
+   * When enabled, clients will only send the cookie back when the current domain _and_ top-level domain matches.
+   *
+   * This is an attribute that has not yet been fully standardized, and may change in the future.
+   * This also means clients may ignore this attribute until they understand it. More information
+   * about can be found in [the proposal](https://github.com/privacycg/CHIPS).
+   */
+  partitioned?: boolean;
+  /**
+   * Specifies the value for the [`Priority` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).
+   *
+   * - `'low'` will set the `Priority` attribute to `Low`.
+   * - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.
+   * - `'high'` will set the `Priority` attribute to `High`.
+   *
+   * More information about priority levels can be found in [the specification](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).
+   */
+  priority?: "low" | "medium" | "high";
+  /**
+   * Specifies the value for the [`SameSite` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7).
+   *
+   * - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
+   * - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement.
+   * - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
+   * - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
+   *
+   * More information about enforcement levels can be found in [the specification](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7).
+   */
+  sameSite?: boolean | "lax" | "strict" | "none";
+}
+/**
+ * Backward compatibility serialize options.
+ */
+type SerializeOptions = StringifyOptions & Omit<SetCookie, "name" | "value">;
+//#endregion
+//#region ../../node_modules/.pnpm/react-router@7.15.0_react-dom@19.2.5_react@19.2.5__react@19.2.5/node_modules/react-router/dist/development/index.d.mts
+/**
+ * A HTTP cookie.
+ *
+ * A Cookie is a logical container for metadata about a HTTP cookie; its name
+ * and options. But it doesn't contain a value. Instead, it has `parse()` and
+ * `serialize()` methods that allow a single instance to be reused for
+ * parsing/encoding multiple different values.
+ *
+ * @see https://remix.run/utils/cookies#cookie-api
+ */
+interface Cookie {
+  /**
+   * The name of the cookie, used in the `Cookie` and `Set-Cookie` headers.
+   */
+  readonly name: string;
+  /**
+   * True if this cookie uses one or more secrets for verification.
+   */
+  readonly isSigned: boolean;
+  /**
+   * The Date this cookie expires.
+   *
+   * Note: This is calculated at access time using `maxAge` when no `expires`
+   * option is provided to `createCookie()`.
+   */
+  readonly expires?: Date;
+  /**
+   * Parses a raw `Cookie` header and returns the value of this cookie or
+   * `null` if it's not present.
+   */
+  parse(cookieHeader: string | null, options?: ParseOptions): Promise<any>;
+  /**
+   * Serializes the given value to a string and returns the `Set-Cookie`
+   * header.
+   */
+  serialize(value: any, options?: SerializeOptions): Promise<string>;
+}
+/**
+ * Creates a logical container for managing a browser cookie from the server.
+ */
+/**
+ * An object of name/value pairs to be used in the session.
+ */
+interface SessionData {
+  [name: string]: any;
+}
+/**
+ * Session persists data across HTTP requests.
+ *
+ * @see https://reactrouter.com/explanation/sessions-and-cookies#sessions
+ */
+interface Session<Data = SessionData, FlashData = Data> {
+  /**
+   * A unique identifier for this session.
+   *
+   * Note: This will be the empty string for newly created sessions and
+   * sessions that are not backed by a database (i.e. cookie-based sessions).
+   */
+  readonly id: string;
+  /**
+   * The raw data contained in this session.
+   *
+   * This is useful mostly for SessionStorage internally to access the raw
+   * session data to persist.
+   */
+  readonly data: FlashSessionData<Data, FlashData>;
+  /**
+   * Returns `true` if the session has a value for the given `name`, `false`
+   * otherwise.
+   */
+  has(name: (keyof Data | keyof FlashData) & string): boolean;
+  /**
+   * Returns the value for the given `name` in this session.
+   */
+  get<Key extends (keyof Data | keyof FlashData) & string>(name: Key): (Key extends keyof Data ? Data[Key] : undefined) | (Key extends keyof FlashData ? FlashData[Key] : undefined) | undefined;
+  /**
+   * Sets a value in the session for the given `name`.
+   */
+  set<Key extends keyof Data & string>(name: Key, value: Data[Key]): void;
+  /**
+   * Sets a value in the session that is only valid until the next `get()`.
+   * This can be useful for temporary values, like error messages.
+   */
+  flash<Key extends keyof FlashData & string>(name: Key, value: FlashData[Key]): void;
+  /**
+   * Removes a value from the session.
+   */
+  unset(name: keyof Data & string): void;
+}
+type FlashSessionData<Data, FlashData> = Partial<Data & { [Key in keyof FlashData as FlashDataKey<Key & string>]: FlashData[Key] }>;
+type FlashDataKey<Key extends string> = `__flash_${Key}__`;
+/**
+ * SessionStorage stores session data between HTTP requests and knows how to
+ * parse and create cookies.
+ *
+ * A SessionStorage creates Session objects using a `Cookie` header as input.
+ * Then, later it generates the `Set-Cookie` header to be used in the response.
+ */
+interface SessionStorage<Data = SessionData, FlashData = Data> {
+  /**
+   * Parses a Cookie header from a HTTP request and returns the associated
+   * Session. If there is no session associated with the cookie, this will
+   * return a new Session with no data.
+   */
+  getSession: (cookieHeader?: string | null, options?: ParseOptions) => Promise<Session<Data, FlashData>>;
+  /**
+   * Stores all data in the Session and returns the Set-Cookie header to be
+   * used in the HTTP response.
+   */
+  commitSession: (session: Session<Data, FlashData>, options?: SerializeOptions) => Promise<string>;
+  /**
+   * Deletes all data associated with the Session and returns the Set-Cookie
+   * header to be used in the HTTP response.
+   */
+  destroySession: (session: Session<Data, FlashData>, options?: SerializeOptions) => Promise<string>;
+}
+/**
+ * SessionIdStorageStrategy is designed to allow anyone to easily build their
+ * own SessionStorage using `createSessionStorage(strategy)`.
+ *
+ * This strategy describes a common scenario where the session id is stored in
+ * a cookie but the actual session data is stored elsewhere, usually in a
+ * database or on disk. A set of create, read, update, and delete operations
+ * are provided for managing the session data.
+ */
+//#endregion
 //#region src/intl/language-detector.d.ts
 interface LanguageDetectorOption {
   /**

package/dist/text/index.mjs

@@ -5,7 +5,7 @@ function formatBytes(bytes, decimals = 2) {
 	* In binary - change k to 1024
 	*/
 	const k = 1e3;
-	const dm = decimals < 0 ? 0 : decimals;
+	const dm = Math.max(decimals, 0);
 	const sizes = [
 		"Bytes",
 		"KB",

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@regardio/js",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "private": false,
   "description": "Regardio JavaScript utilities",
   "keywords": [
@@ -54,27 +54,32 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "pnpm-lock.yaml"
   ],
   "dependencies": {
     "cookie-es": "3.1.1",
-    "intl-parse-accept-language": "1.0.0",
-    "react-router": "7.14.2"
+    "intl-parse-accept-language": "1.0.0"
   },
   "devDependencies": {
+    "react-router": "7.15.0",
     "@total-typescript/ts-reset": "0.6.1",
     "@types/node": "25.6.0",
     "@vitest/coverage-v8": "4.1.5",
     "@vitest/ui": "4.1.5",
-    "tsdown": "0.21.9",
+    "tsdown": "0.21.10",
     "vitest": "4.1.5",
-    "@regardio/dev": "2.0.2"
+    "@regardio/dev": "2.3.0"
   },
   "scripts": {
     "build": "tsdown",
     "clean": "rimraf .turbo dist",
     "dev": "tsdown --watch",
     "fix": "run-s fix:pkg fix:md fix:biome",
+    "release": "commit-and-tag-version",
+    "release:major": "commit-and-tag-version --release-as major",
+    "release:minor": "commit-and-tag-version --release-as minor",
+    "release:patch": "commit-and-tag-version --release-as patch",
     "fix:biome": "biome check --write --unsafe .",
     "fix:md": "markdownlint-cli2 --config ../../.markdownlint-cli2.jsonc --fix",
     "fix:pkg": "sort-package-json",