@develia/commons 0.5.0 → 0.6.1

package/dist/uuid.js

@@ -7,7 +7,7 @@ const MAX_V7_MILLISECONDS = 0xffffffffffff;
  * such as `019a4f8b-4bae-7d2e-9f10-4a5b6c7d8e9f`.
  *
  * It serializes to its string with `JSON.stringify`, so DTOs carry it as text; read those
- * strings back with {@link Uuid.parse} or {@link Uuid.parseOrThrow}.
+ * strings back with {@link Uuid.parse} or {@link Uuid.tryParse}.
  */
 export default class Uuid {
     constructor(value) {
@@ -60,39 +60,39 @@ export default class Uuid {
     /**
      * Reads a UUID in canonical form, in any letter case, as {@link Uuid.isValid} accepts it.
      *
-     * @returns The UUID, or `null` when the value is not one.
+     * @throws {SyntaxError} If the value is not a UUID.
      */
     static parse(value) {
-        if (typeof value !== 'string' || !Uuid.isValid(value)) {
-            return null;
+        const uuid = Uuid.tryParse(value);
+        if (uuid === undefined) {
+            throw new SyntaxError(`Invalid UUID "${value}".`);
         }
-        return new Uuid(value.toLowerCase());
+        return uuid;
     }
     /**
-     * Reads a UUID in canonical form, in any letter case.
+     * Reads a UUID in canonical form, in any letter case, as {@link Uuid.isValid} accepts it.
      *
-     * @throws {SyntaxError} If the value is not a UUID.
+     * @returns The UUID, or `undefined` when the value is not one.
      */
-    static parseOrThrow(value) {
-        const uuid = Uuid.parse(value);
-        if (uuid === null) {
-            throw new SyntaxError(`Invalid UUID "${value}".`);
+    static tryParse(value) {
+        if (typeof value !== 'string' || !Uuid.isValid(value)) {
+            return undefined;
         }
-        return uuid;
+        return new Uuid(value.toLowerCase());
     }
     /**
-     * Returns the RFC 9562 version, from 1 to 8, or 0 for the Nil UUID and 15 for the Max UUID.
+     * The RFC 9562 version, from 1 to 8, or 0 for the Nil UUID and 15 for the Max UUID.
      */
-    getVersion() {
+    get version() {
         return Number.parseInt(this.value.charAt(14), 16);
     }
     /**
-     * Returns the moment a version 7 UUID encodes, with millisecond precision.
+     * The moment a version 7 UUID encodes, with millisecond precision.
      *
-     * @returns The moment, or `null` for other versions.
+     * It is `null` for other versions.
      */
-    getDate() {
-        if (this.getVersion() !== 7) {
+    get date() {
+        if (this.version !== 7) {
             return null;
         }
         const milliseconds = Number.parseInt(this.value.slice(0, 8) + this.value.slice(9, 13), 16);

package/dist/uuid.js.map

@@ -1 +1 @@
-{"version":3,"file":"uuid.js","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"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","sourcesContent":["import {Nullable} from './types.js';\n\n/** Versions 1 to 8 with the RFC variant, plus the Nil and Max UUIDs of RFC 9562 sections 5.9 and 5.10. */\nconst PATTERN = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|0{8}-0{4}-0{4}-0{4}-0{12}|f{8}-f{4}-f{4}-f{4}-f{12})$/i;\n\n/** Largest Unix timestamp in milliseconds that fits in the 48 bits of a version 7 UUID. */\nconst MAX_V7_MILLISECONDS = 0xffffffffffff;\n\n/**\n * Immutable universally unique identifier (RFC 9562), kept in lowercase canonical form,\n * such as `019a4f8b-4bae-7d2e-9f10-4a5b6c7d8e9f`.\n *\n * It serializes to its string with `JSON.stringify`, so DTOs carry it as text; read those\n * strings back with {@link Uuid.parse} or {@link Uuid.parseOrThrow}.\n */\nexport default class Uuid {\n    private readonly value: string;\n\n    private constructor(value: string) {\n        this.value = value;\n    }\n\n    /**\n     * Generates a version 4 UUID from 122 random bits of a cryptographically secure source.\n     *\n     * Unlike `crypto.randomUUID()`, it also works in browser contexts that are not secure, such as\n     * a development site served over HTTP.\n     */\n    static generateV4(): Uuid {\n        const bytes = new Uint8Array(16);\n        globalThis.crypto.getRandomValues(bytes);\n\n        return Uuid.createWithVersion(bytes, 4);\n    }\n\n    /**\n     * Generates a version 7 UUID: a 48-bit Unix timestamp in milliseconds followed by 74 random bits\n     * from a cryptographically secure source, so identifiers sort by creation time.\n     *\n     * Identifiers generated within the same millisecond keep no particular order among themselves.\n     *\n     * @param date Moment the UUID encodes; the current time when omitted.\n     * @throws {RangeError} If the date is invalid, before the Unix epoch or beyond the 48-bit range.\n     */\n    static generateV7(date: Date = new Date()): Uuid {\n        const milliseconds = date.getTime();\n        if (!Number.isInteger(milliseconds) || milliseconds < 0 || milliseconds > MAX_V7_MILLISECONDS) {\n            throw new RangeError('A version 7 UUID can only encode a valid date from the Unix epoch on.');\n        }\n\n        const bytes = new Uint8Array(16);\n        globalThis.crypto.getRandomValues(bytes);\n        let remaining = milliseconds;\n        for (let index = 5; index >= 0; index--) {\n            bytes[index] = remaining % 256;\n            remaining = Math.floor(remaining / 256);\n        }\n\n        return Uuid.createWithVersion(bytes, 7);\n    }\n\n    /**\n     * Checks if a value is a UUID in canonical form, in any letter case: one of RFC 9562 versions 1 to 8,\n     * or its Nil UUID (all zeros) or Max UUID (all ones).\n     *\n     * It returns a plain boolean rather than a type guard: a string that is not a UUID is still a\n     * string, which a guard would narrow to `never`.\n     */\n    static isValid(value: unknown): boolean {\n        return typeof value === 'string' && PATTERN.test(value);\n    }\n\n    /**\n     * Reads a UUID in canonical form, in any letter case, as {@link Uuid.isValid} accepts it.\n     *\n     * @returns The UUID, or `null` when the value is not one.\n     */\n    static parse(value: unknown): Nullable<Uuid> {\n        if (typeof value !== 'string' || !Uuid.isValid(value)) {\n            return null;\n        }\n\n        return new Uuid(value.toLowerCase());\n    }\n\n    /**\n     * Reads a UUID in canonical form, in any letter case.\n     *\n     * @throws {SyntaxError} If the value is not a UUID.\n     */\n    static parseOrThrow(value: string): Uuid {\n        const uuid = Uuid.parse(value);\n        if (uuid === null) {\n            throw new SyntaxError(`Invalid UUID \"${value}\".`);\n        }\n\n        return uuid;\n    }\n\n    /**\n     * Returns the RFC 9562 version, from 1 to 8, or 0 for the Nil UUID and 15 for the Max UUID.\n     */\n    getVersion(): number {\n        return Number.parseInt(this.value.charAt(14), 16);\n    }\n\n    /**\n     * Returns the moment a version 7 UUID encodes, with millisecond precision.\n     *\n     * @returns The moment, or `null` for other versions.\n     */\n    getDate(): Nullable<Date> {\n        if (this.getVersion() !== 7) {\n            return null;\n        }\n\n        const milliseconds = Number.parseInt(this.value.slice(0, 8) + this.value.slice(9, 13), 16);\n        return new Date(milliseconds);\n    }\n\n    equals(other: Uuid): boolean {\n        return this.value === other.value;\n    }\n\n    /**\n     * Returns the UUID in lowercase canonical form.\n     */\n    toString(): string {\n        return this.value;\n    }\n\n    toJSON(): string {\n        return this.value;\n    }\n\n    /**\n     * Sets the version and the RFC 9562 variant bits of 16 bytes and wraps them as a UUID.\n     *\n     * @param bytes Exactly 16 bytes; only the version and variant bits are overwritten.\n     * @param version From 1 to 8.\n     */\n    private static createWithVersion(bytes: Uint8Array, version: number): Uuid {\n        bytes[6] = (bytes[6] & 0x0f) | (version << 4);\n        bytes[8] = (bytes[8] & 0x3f) | 0x80;\n\n        let hex = '';\n        for (const byte of bytes) {\n            hex += byte.toString(16).padStart(2, '0');\n        }\n\n        return new Uuid(`${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`);\n    }\n}\n"]}
+{"version":3,"file":"uuid.js","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"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","sourcesContent":["import {Nullable} from './types.js';\n\n/** Versions 1 to 8 with the RFC variant, plus the Nil and Max UUIDs of RFC 9562 sections 5.9 and 5.10. */\nconst PATTERN = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|0{8}-0{4}-0{4}-0{4}-0{12}|f{8}-f{4}-f{4}-f{4}-f{12})$/i;\n\n/** Largest Unix timestamp in milliseconds that fits in the 48 bits of a version 7 UUID. */\nconst MAX_V7_MILLISECONDS = 0xffffffffffff;\n\n/**\n * Immutable universally unique identifier (RFC 9562), kept in lowercase canonical form,\n * such as `019a4f8b-4bae-7d2e-9f10-4a5b6c7d8e9f`.\n *\n * It serializes to its string with `JSON.stringify`, so DTOs carry it as text; read those\n * strings back with {@link Uuid.parse} or {@link Uuid.tryParse}.\n */\nexport default class Uuid {\n    private readonly value: string;\n\n    private constructor(value: string) {\n        this.value = value;\n    }\n\n    /**\n     * Generates a version 4 UUID from 122 random bits of a cryptographically secure source.\n     *\n     * Unlike `crypto.randomUUID()`, it also works in browser contexts that are not secure, such as\n     * a development site served over HTTP.\n     */\n    static generateV4(): Uuid {\n        const bytes = new Uint8Array(16);\n        globalThis.crypto.getRandomValues(bytes);\n\n        return Uuid.createWithVersion(bytes, 4);\n    }\n\n    /**\n     * Generates a version 7 UUID: a 48-bit Unix timestamp in milliseconds followed by 74 random bits\n     * from a cryptographically secure source, so identifiers sort by creation time.\n     *\n     * Identifiers generated within the same millisecond keep no particular order among themselves.\n     *\n     * @param date Moment the UUID encodes; the current time when omitted.\n     * @throws {RangeError} If the date is invalid, before the Unix epoch or beyond the 48-bit range.\n     */\n    static generateV7(date: Date = new Date()): Uuid {\n        const milliseconds = date.getTime();\n        if (!Number.isInteger(milliseconds) || milliseconds < 0 || milliseconds > MAX_V7_MILLISECONDS) {\n            throw new RangeError('A version 7 UUID can only encode a valid date from the Unix epoch on.');\n        }\n\n        const bytes = new Uint8Array(16);\n        globalThis.crypto.getRandomValues(bytes);\n        let remaining = milliseconds;\n        for (let index = 5; index >= 0; index--) {\n            bytes[index] = remaining % 256;\n            remaining = Math.floor(remaining / 256);\n        }\n\n        return Uuid.createWithVersion(bytes, 7);\n    }\n\n    /**\n     * Checks if a value is a UUID in canonical form, in any letter case: one of RFC 9562 versions 1 to 8,\n     * or its Nil UUID (all zeros) or Max UUID (all ones).\n     *\n     * It returns a plain boolean rather than a type guard: a string that is not a UUID is still a\n     * string, which a guard would narrow to `never`.\n     */\n    static isValid(value: unknown): boolean {\n        return typeof value === 'string' && PATTERN.test(value);\n    }\n\n    /**\n     * Reads a UUID in canonical form, in any letter case, as {@link Uuid.isValid} accepts it.\n     *\n     * @throws {SyntaxError} If the value is not a UUID.\n     */\n    static parse(value: string): Uuid {\n        const uuid = Uuid.tryParse(value);\n        if (uuid === undefined) {\n            throw new SyntaxError(`Invalid UUID \"${value}\".`);\n        }\n\n        return uuid;\n    }\n\n    /**\n     * Reads a UUID in canonical form, in any letter case, as {@link Uuid.isValid} accepts it.\n     *\n     * @returns The UUID, or `undefined` when the value is not one.\n     */\n    static tryParse(value: unknown): Uuid | undefined {\n        if (typeof value !== 'string' || !Uuid.isValid(value)) {\n            return undefined;\n        }\n\n        return new Uuid(value.toLowerCase());\n    }\n\n    /**\n     * The RFC 9562 version, from 1 to 8, or 0 for the Nil UUID and 15 for the Max UUID.\n     */\n    get version(): number {\n        return Number.parseInt(this.value.charAt(14), 16);\n    }\n\n    /**\n     * The moment a version 7 UUID encodes, with millisecond precision.\n     *\n     * It is `null` for other versions.\n     */\n    get date(): Nullable<Date> {\n        if (this.version !== 7) {\n            return null;\n        }\n\n        const milliseconds = Number.parseInt(this.value.slice(0, 8) + this.value.slice(9, 13), 16);\n        return new Date(milliseconds);\n    }\n\n    equals(other: Uuid): boolean {\n        return this.value === other.value;\n    }\n\n    /**\n     * Returns the UUID in lowercase canonical form.\n     */\n    toString(): string {\n        return this.value;\n    }\n\n    toJSON(): string {\n        return this.value;\n    }\n\n    /**\n     * Sets the version and the RFC 9562 variant bits of 16 bytes and wraps them as a UUID.\n     *\n     * @param bytes Exactly 16 bytes; only the version and variant bits are overwritten.\n     * @param version From 1 to 8.\n     */\n    private static createWithVersion(bytes: Uint8Array, version: number): Uuid {\n        bytes[6] = (bytes[6] & 0x0f) | (version << 4);\n        bytes[8] = (bytes[8] & 0x3f) | 0x80;\n\n        let hex = '';\n        for (const byte of bytes) {\n            hex += byte.toString(16).padStart(2, '0');\n        }\n\n        return new Uuid(`${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`);\n    }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@develia/commons",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "author": {
     "name": "Antonio Gil Espinosa",
     "email": "antonio.gil.espinosa@gmail.com",

package/src/parse.ts

@@ -1,6 +1,6 @@
 // parse.ts
 /**
- * Options for {@link parseBoolean}.
+ * Options for {@link tryParseBoolean} and {@link parseBoolean}.
  */
 export interface ParseBooleanOptions {
     /**
@@ -19,7 +19,7 @@ export interface ParseBooleanOptions {
 }
 
 /**
- * Options for {@link parseInteger}.
+ * Options for {@link tryParseInteger} and {@link parseInteger}.
  */
 export interface ParseIntegerOptions {
     /**
@@ -37,7 +37,7 @@ export interface ParseIntegerOptions {
 }
 
 /**
- * Options for {@link parseDecimal}.
+ * Options for {@link tryParseDecimal} and {@link parseDecimal}.
  */
 export interface ParseDecimalOptions {
     /**
@@ -75,64 +75,78 @@ function isValidInteger(value: string, radix: number): boolean {
 }
 
 // ============================================
-// parseInteger
+// tryParseInteger / parseInteger
 // ============================================
 
 /**
  * Safely parses a value into an integer.
- * Returns `null` if the value cannot be parsed.
+ * Returns `undefined` if the value cannot be parsed.
  *
- * - `null` or `undefined` → `null`
+ * - `null` or `undefined` → `undefined`
  * - `number` → returned as-is (floats are truncated)
  * - `string` → parsed with the given options
  *
  * @param value - The value to parse.
  * @param options - Optional parsing configuration.
- * @returns The parsed integer, or `null` on failure.
+ * @returns The parsed integer, or `undefined` on failure.
  *
  * @example
  * ```ts
- * parseInteger(42)                                        // 42
- * parseInteger(3.7)                                       // 3
- * parseInteger(null)                                      // null
- * parseInteger(undefined)                                 // null
- * parseInteger("42")                                      // 42
- * parseInteger("1.234.567", { thousandsSeparator: "." })  // 1234567
- * parseInteger("FF", { radix: 16 })                       // 255
- * parseInteger("abc")                                     // null
+ * tryParseInteger(42)                                        // 42
+ * tryParseInteger(3.7)                                       // 3
+ * tryParseInteger(null)                                      // undefined
+ * tryParseInteger(undefined)                                 // undefined
+ * tryParseInteger("42")                                      // 42
+ * tryParseInteger("1.234.567", { thousandsSeparator: "." })  // 1234567
+ * tryParseInteger("FF", { radix: 16 })                       // 255
+ * tryParseInteger("abc")                                     // undefined
  * ```
  */
-export function parseInteger(
+export function tryParseInteger(
     value: string | number | null | undefined,
     options: ParseIntegerOptions = {}
-): number | null {
-    if (value === null || value === undefined) return null;
+): number | undefined {
+    if (value === null || value === undefined) return undefined;
 
     if (typeof value === "number") {
-        return Number.isFinite(value) ? Math.trunc(value) : null;
+        return Number.isFinite(value) ? Math.trunc(value) : undefined;
     }
 
     const { radix = 10, thousandsSeparator } = options;
 
     const cleaned = stripThousands(value.trim(), thousandsSeparator);
 
-    if (cleaned === "") return null;
-    if (!isValidInteger(cleaned, radix)) return null;
+    if (cleaned === "") return undefined;
+    if (!isValidInteger(cleaned, radix)) return undefined;
 
     const parsed = Number.parseInt(cleaned, radix);
 
-    return Number.isNaN(parsed) ? null : parsed;
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+/**
+ * Parses a value into an integer as {@link tryParseInteger} does.
+ *
+ * @throws {SyntaxError} If the value cannot be parsed.
+ */
+export function parseInteger(value: string | number, options: ParseIntegerOptions = {}): number {
+    const parsed = tryParseInteger(value, options);
+    if (parsed === undefined) {
+        throw new SyntaxError(`Invalid integer "${value}".`);
+    }
+
+    return parsed;
 }
 
 // ============================================
-// parseDecimal
+// tryParseDecimal / parseDecimal
 // ============================================
 
 /**
  * Safely parses a value into a floating-point number.
- * Returns `null` if the value cannot be parsed.
+ * Returns `undefined` if the value cannot be parsed.
  *
- * - `null` or `undefined` → `null`
+ * - `null` or `undefined` → `undefined`
  * - `number` → returned as-is (if finite)
  * - `string` → parsed with the given options
  *
@@ -141,50 +155,64 @@ export function parseInteger(
  *
  * @param value - The value to parse.
  * @param options - Optional parsing configuration.
- * @returns The parsed float, or `null` on failure.
+ * @returns The parsed float, or `undefined` on failure.
  *
  * @example
  * ```ts
- * parseDecimal(3.14)                                                       // 3.14
- * parseDecimal(null)                                                       // null
- * parseDecimal(undefined)                                                  // null
- * parseDecimal("3.14")                                                     // 3.14
- * parseDecimal("3,14", { decimalSeparator: "," })                          // 3.14
- * parseDecimal("1.234,56", { decimalSeparator: ",", thousandsSeparator: "." }) // 1234.56
- * parseDecimal("abc")                                                      // null
+ * tryParseDecimal(3.14)                                                       // 3.14
+ * tryParseDecimal(null)                                                       // undefined
+ * tryParseDecimal(undefined)                                                  // undefined
+ * tryParseDecimal("3.14")                                                     // 3.14
+ * tryParseDecimal("3,14", { decimalSeparator: "," })                          // 3.14
+ * tryParseDecimal("1.234,56", { decimalSeparator: ",", thousandsSeparator: "." }) // 1234.56
+ * tryParseDecimal("abc")                                                      // undefined
  * ```
  */
-export function parseDecimal(
+export function tryParseDecimal(
     value: string | number | null | undefined,
     options: ParseDecimalOptions = {}
-): number | null {
-    if (value === null || value === undefined) return null;
+): number | undefined {
+    if (value === null || value === undefined) return undefined;
 
     if (typeof value === "number") {
-        return Number.isFinite(value) ? value : null;
+        return Number.isFinite(value) ? value : undefined;
     }
 
     const { decimalSeparator = ".", thousandsSeparator } = options;
 
     let cleaned = stripThousands(value.trim(), thousandsSeparator);
 
-    if (cleaned === "") return null;
+    if (cleaned === "") return undefined;
 
     if (decimalSeparator === ",") {
         const commaCount = (cleaned.match(/,/g) || []).length;
-        if (commaCount > 1) return null;
+        if (commaCount > 1) return undefined;
         cleaned = cleaned.replace(",", ".");
     }
 
-    if (!/^[+-]?\d+(\.\d+)?$/.test(cleaned)) return null;
+    if (!/^[+-]?\d+(\.\d+)?$/.test(cleaned)) return undefined;
 
     const parsed = Number.parseFloat(cleaned);
 
-    return Number.isNaN(parsed) || !Number.isFinite(parsed) ? null : parsed;
+    return Number.isNaN(parsed) || !Number.isFinite(parsed) ? undefined : parsed;
+}
+
+/**
+ * Parses a value into a decimal number as {@link tryParseDecimal} does.
+ *
+ * @throws {SyntaxError} If the value cannot be parsed.
+ */
+export function parseDecimal(value: string | number, options: ParseDecimalOptions = {}): number {
+    const parsed = tryParseDecimal(value, options);
+    if (parsed === undefined) {
+        throw new SyntaxError(`Invalid decimal number "${value}".`);
+    }
+
+    return parsed;
 }
 
 // ============================================
-// parseBoolean
+// tryParseBoolean / parseBoolean
 // ============================================
 
 const DEFAULT_TRUTHY = ["true", "1", "yes", "si", "sí", "on"];
@@ -192,9 +220,9 @@ const DEFAULT_FALSY = ["false", "0", "no", "off"];
 
 /**
  * Safely parses a value into a boolean.
- * Returns `null` if the value cannot be interpreted as boolean.
+ * Returns `undefined` if the value cannot be interpreted as boolean.
  *
- * - `null` or `undefined` → `null`
+ * - `null` or `undefined` → `undefined`
  * - `boolean` → returned as-is
  * - `number` → `0` is `false`, any other finite number is `true`
  * - `string` → matched case-insensitively against known truthy/falsy values
@@ -204,43 +232,43 @@ const DEFAULT_FALSY = ["false", "0", "no", "off"];
  *
  * @param value - The value to parse.
  * @param options - Optional parsing configuration.
- * @returns The parsed boolean, or `null` on failure.
+ * @returns The parsed boolean, or `undefined` on failure.
  *
  * @example
  * ```ts
- * parseBoolean(true)                                    // true
- * parseBoolean(false)                                   // false
- * parseBoolean(1)                                       // true
- * parseBoolean(0)                                       // false
- * parseBoolean(null)                                    // null
- * parseBoolean(undefined)                               // null
- * parseBoolean("yes")                                   // true
- * parseBoolean("no")                                    // false
- * parseBoolean("sí")                                    // true
- * parseBoolean("TRUE")                                  // true
- * parseBoolean("oui")                                   // null
- * parseBoolean("oui", { extraTruthy: ["oui"] })         // true
- * parseBoolean("nein", { extraFalsy: ["nein"] })        // false
- * parseBoolean("whatever")                              // null
+ * tryParseBoolean(true)                                    // true
+ * tryParseBoolean(false)                                   // false
+ * tryParseBoolean(1)                                       // true
+ * tryParseBoolean(0)                                       // false
+ * tryParseBoolean(null)                                    // undefined
+ * tryParseBoolean(undefined)                               // undefined
+ * tryParseBoolean("yes")                                   // true
+ * tryParseBoolean("no")                                    // false
+ * tryParseBoolean("sí")                                    // true
+ * tryParseBoolean("TRUE")                                  // true
+ * tryParseBoolean("oui")                                   // undefined
+ * tryParseBoolean("oui", { extraTruthy: ["oui"] })         // true
+ * tryParseBoolean("nein", { extraFalsy: ["nein"] })        // false
+ * tryParseBoolean("whatever")                              // undefined
  * ```
  */
-export function parseBoolean(
+export function tryParseBoolean(
     value: string | number | boolean | null | undefined,
     options: ParseBooleanOptions = {}
-): boolean | null {
-    if (value === null || value === undefined) return null;
+): boolean | undefined {
+    if (value === null || value === undefined) return undefined;
 
     if (typeof value === "boolean") return value;
 
     if (typeof value === "number") {
-        return Number.isFinite(value) ? value !== 0 : null;
+        return Number.isFinite(value) ? value !== 0 : undefined;
     }
 
     const { extraTruthy = [], extraFalsy = [] } = options;
 
     const normalized = value.trim().toLowerCase();
 
-    if (normalized === "") return null;
+    if (normalized === "") return undefined;
 
     const truthy = [...DEFAULT_TRUTHY, ...extraTruthy.map((s) => s.toLowerCase())];
     const falsy = [...DEFAULT_FALSY, ...extraFalsy.map((s) => s.toLowerCase())];
@@ -248,5 +276,19 @@ export function parseBoolean(
     if (truthy.includes(normalized)) return true;
     if (falsy.includes(normalized)) return false;
 
-    return null;
-}
+    return undefined;
+}
+
+/**
+ * Parses a value into a boolean as {@link tryParseBoolean} does.
+ *
+ * @throws {SyntaxError} If the value cannot be parsed.
+ */
+export function parseBoolean(value: string | number | boolean, options: ParseBooleanOptions = {}): boolean {
+    const parsed = tryParseBoolean(value, options);
+    if (parsed === undefined) {
+        throw new SyntaxError(`Invalid boolean "${value}".`);
+    }
+
+    return parsed;
+}

package/src/range.ts

@@ -1,7 +1,7 @@
 export default class Range<T> {
 
-    private readonly start: T;
-    private readonly end: T;
+    public readonly start: T;
+    public readonly end: T;
 
     /**
      * Range constructor.
@@ -86,20 +86,6 @@ export default class Range<T> {
             (this.start < obj && this.end > obj);
     }
 
-    /**
-     * @returns T
-     */
-    public getStart(): T {
-        return this.start;
-    }
-
-    /**
-     * @returns T
-     */
-    public getEnd(): T {
-        return this.end;
-    }
-
     /**
      * Finds the intersection between two sets of ranges.
      *

package/src/stopwatch.ts

@@ -2,7 +2,7 @@ import TimeSpan from "./timespan.js";
 
 export default class Stopwatch {
     private startTime: number | null = null;
-    private elapsedTime: number | null = null;
+    private elapsedMilliseconds: number | null = null;
 
     /*static measure<T>(callback: () => T, measure: { value: TimeSpan | null }): T {
         const stopwatch = new Stopwatch();
@@ -11,33 +11,33 @@ export default class Stopwatch {
             return callback();
         } finally {
             stopwatch.stop();
-            measure.value = stopwatch.getElapsedTime();
+            measure.value = stopwatch.elapsedTime;
         }
     }*/
 
     start(): void {
         this.startTime = performance.now();
-        this.elapsedTime = null;
+        this.elapsedMilliseconds = null;
     }
 
     stop(): void {
         if (this.startTime !== null) {
-            this.elapsedTime = performance.now() - this.startTime;
+            this.elapsedMilliseconds = performance.now() - this.startTime;
             this.startTime = null;
         }
     }
 
     resume(): void {
-        if (this.elapsedTime !== null) {
-            this.startTime = performance.now() - this.elapsedTime;
-            this.elapsedTime = null;
+        if (this.elapsedMilliseconds !== null) {
+            this.startTime = performance.now() - this.elapsedMilliseconds;
+            this.elapsedMilliseconds = null;
         }
     }
 
-    getElapsedTime(): TimeSpan {
+    get elapsedTime(): TimeSpan {
         if (this.startTime !== null) {
             return TimeSpan.fromMilliseconds(performance.now() - this.startTime);
         }
-        return TimeSpan.fromMilliseconds(this.elapsedTime ?? 0.0);
+        return TimeSpan.fromMilliseconds(this.elapsedMilliseconds ?? 0.0);
     }
 }

package/src/string.ts

@@ -157,3 +157,27 @@ export function toPascalCase(str: string): string {
 export function toConstantCase(str: string): string {
     return toWords(str).join('_').toUpperCase();
 }
+
+const FILE_SIZE_UNITS: readonly string[] = Object.freeze(['B', 'KB', 'MB', 'GB', 'TB', 'PB']);
+
+/**
+ * Formats a size in bytes with the largest unit it fills, in powers of 1024: `340 B`, `1.2 MB`.
+ *
+ * Bytes are written whole and the larger units with at most one decimal, with the separators of the locale.
+ *
+ * @param {number} bytes - The size in bytes; a negative or non-finite size is formatted as zero.
+ * @param {string} [locale] - The locale of the number, such as `es-ES`; the one of the runtime when omitted.
+ * @return {string} The number, a space and the unit.
+ */
+export function formatFileSize(bytes: number, locale?: string): string {
+    let size = Number.isFinite(bytes) && bytes > 0 ? bytes : 0;
+    let unitIndex = 0;
+    while (size >= 1024 && unitIndex < FILE_SIZE_UNITS.length - 1) {
+        size /= 1024;
+        unitIndex++;
+    }
+
+    const maximumFractionDigits = unitIndex === 0 ? 0 : 1;
+
+    return `${size.toLocaleString(locale, {maximumFractionDigits})} ${FILE_SIZE_UNITS[unitIndex]}`;
+}

package/src/timespan.ts

@@ -10,42 +10,37 @@ export default class TimeSpan {
 
 
     /**
-     * Gets the time interval in seconds.
-     * @returns {number} The duration in seconds.
+     * The whole duration in seconds.
      */
-    getTotalSeconds(): number {
+    get totalSeconds(): number {
         return this.milliseconds / 1000;
     }
 
     /**
-     * Gets the time interval in minutes.
-     * @returns {number} The duration in minutes.
+     * The whole duration in minutes.
      */
-    getTotalMinutes(): number {
+    get totalMinutes(): number {
         return this.milliseconds / (1000 * 60);
     }
 
     /**
-     * Gets the time interval in hours.
-     * @returns {number} The duration in hours.
+     * The whole duration in hours.
      */
-    getTotalHours(): number {
+    get totalHours(): number {
         return this.milliseconds / (1000 * 60 * 60);
     }
 
     /**
-     * Gets the time interval in days.
-     * @returns {number} The duration in days.
+     * The whole duration in days.
      */
-    getTotalDays(): number {
+    get totalDays(): number {
         return this.milliseconds / (1000 * 60 * 60 * 24);
     }
 
     /**
-     * Gets the time interval in weeks.
-     * @returns {number} The duration in weeks.
+     * The whole duration in weeks.
      */
-    getTotalWeeks(): number {
+    get totalWeeks(): number {
         return this.milliseconds / (1000 * 60 * 60 * 24 * 7);
     }