@naturalcycles/js-lib 15.93.2 → 15.93.4

package/dist/datetime/localTime.js

@@ -868,8 +868,7 @@ class LocalTimeFactory {
     isTimezoneValid(tz) {
         if (tz === 'UTC')
             return true; // we deliberately consider UTC a valid timezone, while it's mostly used in testing
-        // oxlint-disable-next-line no-restricted-globals
-        return Intl.supportedValuesOf('timeZone').includes(tz);
+        return Intl2.getSupportedTimezones().includes(tz);
     }
     sort(items, dir = 'asc', opt = {}) {
         const cmp = comparators.by((lt) => lt.$date.valueOf(), { dir });

package/dist/intl/intl.d.ts

@@ -7,13 +7,41 @@ import type { IANATimezone } from '../types.js';
  *
  * Methods accept non-optional arguments consciously,
  * to be able to cache them better. Just pass {} for options.
+ *
+ * The cache is never evicted, it grows with each unique combination of arguments.
+ * Don't pass unbounded dynamic values (e.g arbitrary user input) as locales or options.
  */
 declare class MemoizedIntl {
+    /**
+     * Escape hatch: for when you want to use native Intl, but linter screams at you - then you can use
+     * Intl2.Intl.*
+     *
+     * Prefer the memoized methods of Intl2 for creating formatters; use this for static functions
+     * (e.g `getCanonicalLocales`), `instanceof` checks, and cheap objects like Locale.
+     *
+     * Intl.Locale is not wrapped consciously: it was benchmarked and does NOT benefit from memoization.
+     * It's cheap to create (~1.3µs raw vs ~0.2µs cache hit, so ~1µs saved), while its tag often comes
+     * from runtime data (e.g request language), which would grow the never-evicted cache unboundedly.
+     * Use `new Intl2.Intl.Locale(tag)` instead.
+     */
+    readonly Intl: typeof Intl;
     /**
      * Returns the IANA timezone e.g `Europe/Stockholm`.
      * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     *
+     * Memoized, so it returns the timezone at the time of the first call.
+     * Changing `process.env.TZ` at runtime after that is not reflected.
      */
     getTimezone(): IANATimezone;
+    /**
+     * Returns the list of IANA timezones supported by the runtime (~420 entries).
+     * Memoized, because V8 rebuilds the list on every call (~70µs).
+     *
+     * The list contains canonical CLDR ids only, so valid aliases are missing from it,
+     * e.g `UTC` and `Europe/Kyiv` (listed as `Europe/Kiev`).
+     * Don't use it to validate user input as is.
+     */
+    getSupportedTimezones(): readonly IANATimezone[];
     DateTimeFormat(locales: Intl.LocalesArgument, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
     RelativeTimeFormat(locales: Intl.LocalesArgument, options: Intl.RelativeTimeFormatOptions): Intl.RelativeTimeFormat;
     DurationFormat(locales: Intl.LocalesArgument, options: Intl.DurationFormatOptions): Intl.DurationFormat;

package/dist/intl/intl.js

@@ -9,15 +9,45 @@ import { _Memo } from '../decorators/memo.decorator.js';
  *
  * Methods accept non-optional arguments consciously,
  * to be able to cache them better. Just pass {} for options.
+ *
+ * The cache is never evicted, it grows with each unique combination of arguments.
+ * Don't pass unbounded dynamic values (e.g arbitrary user input) as locales or options.
  */
 class MemoizedIntl {
+    /**
+     * Escape hatch: for when you want to use native Intl, but linter screams at you - then you can use
+     * Intl2.Intl.*
+     *
+     * Prefer the memoized methods of Intl2 for creating formatters; use this for static functions
+     * (e.g `getCanonicalLocales`), `instanceof` checks, and cheap objects like Locale.
+     *
+     * Intl.Locale is not wrapped consciously: it was benchmarked and does NOT benefit from memoization.
+     * It's cheap to create (~1.3µs raw vs ~0.2µs cache hit, so ~1µs saved), while its tag often comes
+     * from runtime data (e.g request language), which would grow the never-evicted cache unboundedly.
+     * Use `new Intl2.Intl.Locale(tag)` instead.
+     */
+    Intl = Intl;
     /**
      * Returns the IANA timezone e.g `Europe/Stockholm`.
      * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     *
+     * Memoized, so it returns the timezone at the time of the first call.
+     * Changing `process.env.TZ` at runtime after that is not reflected.
      */
     getTimezone() {
         return Intl.DateTimeFormat().resolvedOptions().timeZone;
     }
+    /**
+     * Returns the list of IANA timezones supported by the runtime (~420 entries).
+     * Memoized, because V8 rebuilds the list on every call (~70µs).
+     *
+     * The list contains canonical CLDR ids only, so valid aliases are missing from it,
+     * e.g `UTC` and `Europe/Kyiv` (listed as `Europe/Kiev`).
+     * Don't use it to validate user input as is.
+     */
+    getSupportedTimezones() {
+        return Intl.supportedValuesOf('timeZone');
+    }
     DateTimeFormat(locales, options) {
         return new Intl.DateTimeFormat(locales, options);
     }
@@ -51,29 +81,49 @@ __decorate([
 ], MemoizedIntl.prototype, "getTimezone", null);
 __decorate([
     _Memo()
+], MemoizedIntl.prototype, "getSupportedTimezones", null);
+__decorate([
+    _Memo({ cacheKeyFn: intlCacheKeyFn })
 ], MemoizedIntl.prototype, "DateTimeFormat", null);
 __decorate([
-    _Memo()
+    _Memo({ cacheKeyFn: intlCacheKeyFn })
 ], MemoizedIntl.prototype, "RelativeTimeFormat", null);
 __decorate([
-    _Memo()
+    _Memo({ cacheKeyFn: intlCacheKeyFn })
 ], MemoizedIntl.prototype, "DurationFormat", null);
 __decorate([
-    _Memo()
+    _Memo({ cacheKeyFn: intlCacheKeyFn })
 ], MemoizedIntl.prototype, "NumberFormat", null);
 __decorate([
-    _Memo()
+    _Memo({ cacheKeyFn: intlCacheKeyFn })
 ], MemoizedIntl.prototype, "Collator", null);
 __decorate([
-    _Memo()
+    _Memo({ cacheKeyFn: intlCacheKeyFn })
 ], MemoizedIntl.prototype, "PluralRules", null);
 __decorate([
-    _Memo()
+    _Memo({ cacheKeyFn: intlCacheKeyFn })
 ], MemoizedIntl.prototype, "ListFormat", null);
 __decorate([
-    _Memo()
+    _Memo({ cacheKeyFn: intlCacheKeyFn })
 ], MemoizedIntl.prototype, "DisplayNames", null);
 __decorate([
-    _Memo()
+    _Memo({ cacheKeyFn: intlCacheKeyFn })
 ], MemoizedIntl.prototype, "Segmenter", null);
 export const Intl2 = new MemoizedIntl();
+/**
+ * Default `jsonMemoSerializer` would serialize `Intl.Locale` instances as `{}`,
+ * making all Locale arguments share one cache key. Convert them to their string tags instead.
+ *
+ * Options keys are serialized in sorted order, so that `{ a, b }` and `{ b, a }` share one cache key.
+ * Passing a keys array as replacer works, because Intl options are flat objects.
+ */
+function intlCacheKeyFn([locales, options]) {
+    return JSON.stringify(localesKey(locales)) + JSON.stringify(options, Object.keys(options).sort());
+}
+function localesKey(locales) {
+    if (locales === undefined)
+        return;
+    if (Array.isArray(locales))
+        return locales.map(String);
+    return String(locales);
+}

package/dist/semver.d.ts

@@ -16,6 +16,8 @@ export type SemverTokens = [major: number, minor: number, patch: number];
  *
  * _semver('1').toString() === '1.0.0'
  *
+ * 4-part strings are treated as equal to 3-part strings, e.g.: '1.2.3.4' === '1.2.3'
+ *
  * @experimental
  */
 export declare class Semver {

package/dist/semver.js

@@ -14,6 +14,8 @@ import { _assert } from './error/assert.js';
  *
  * _semver('1').toString() === '1.0.0'
  *
+ * 4-part strings are treated as equal to 3-part strings, e.g.: '1.2.3.4' === '1.2.3'
+ *
  * @experimental
  */
 export class Semver {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.93.2",
+  "version": "15.93.4",
   "dependencies": {
     "tslib": "^2"
   },

package/src/datetime/localTime.ts

@@ -1016,8 +1016,7 @@ class LocalTimeFactory {
    */
   isTimezoneValid(tz: string): boolean {
     if (tz === 'UTC') return true // we deliberately consider UTC a valid timezone, while it's mostly used in testing
-    // oxlint-disable-next-line no-restricted-globals
-    return Intl.supportedValuesOf('timeZone').includes(tz)
+    return Intl2.getSupportedTimezones().includes(tz as IANATimezone)
   }
 
   sort(items: LocalTime[], dir: SortDirection = 'asc', opt: MutateOptions = {}): LocalTime[] {

package/src/intl/intl.ts

@@ -1,5 +1,5 @@
 import { _Memo } from '../decorators/memo.decorator.js'
-import type { IANATimezone } from '../types.js'
+import type { AnyObject, IANATimezone } from '../types.js'
 
 // oxlint-disable no-restricted-globals
 
@@ -11,18 +11,51 @@ import type { IANATimezone } from '../types.js'
  *
  * Methods accept non-optional arguments consciously,
  * to be able to cache them better. Just pass {} for options.
+ *
+ * The cache is never evicted, it grows with each unique combination of arguments.
+ * Don't pass unbounded dynamic values (e.g arbitrary user input) as locales or options.
  */
 class MemoizedIntl {
+  /**
+   * Escape hatch: for when you want to use native Intl, but linter screams at you - then you can use
+   * Intl2.Intl.*
+   *
+   * Prefer the memoized methods of Intl2 for creating formatters; use this for static functions
+   * (e.g `getCanonicalLocales`), `instanceof` checks, and cheap objects like Locale.
+   *
+   * Intl.Locale is not wrapped consciously: it was benchmarked and does NOT benefit from memoization.
+   * It's cheap to create (~1.3µs raw vs ~0.2µs cache hit, so ~1µs saved), while its tag often comes
+   * from runtime data (e.g request language), which would grow the never-evicted cache unboundedly.
+   * Use `new Intl2.Intl.Locale(tag)` instead.
+   */
+  readonly Intl = Intl
+
   /**
    * Returns the IANA timezone e.g `Europe/Stockholm`.
    * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+   *
+   * Memoized, so it returns the timezone at the time of the first call.
+   * Changing `process.env.TZ` at runtime after that is not reflected.
    */
   @_Memo()
   getTimezone(): IANATimezone {
     return Intl.DateTimeFormat().resolvedOptions().timeZone as IANATimezone
   }
 
+  /**
+   * Returns the list of IANA timezones supported by the runtime (~420 entries).
+   * Memoized, because V8 rebuilds the list on every call (~70µs).
+   *
+   * The list contains canonical CLDR ids only, so valid aliases are missing from it,
+   * e.g `UTC` and `Europe/Kyiv` (listed as `Europe/Kiev`).
+   * Don't use it to validate user input as is.
+   */
   @_Memo()
+  getSupportedTimezones(): readonly IANATimezone[] {
+    return Intl.supportedValuesOf('timeZone') as IANATimezone[]
+  }
+
+  @_Memo({ cacheKeyFn: intlCacheKeyFn })
   DateTimeFormat(
     locales: Intl.LocalesArgument,
     options: Intl.DateTimeFormatOptions,
@@ -30,7 +63,7 @@ class MemoizedIntl {
     return new Intl.DateTimeFormat(locales, options)
   }
 
-  @_Memo()
+  @_Memo({ cacheKeyFn: intlCacheKeyFn })
   RelativeTimeFormat(
     locales: Intl.LocalesArgument,
     options: Intl.RelativeTimeFormatOptions,
@@ -38,7 +71,7 @@ class MemoizedIntl {
     return new Intl.RelativeTimeFormat(locales, options)
   }
 
-  @_Memo()
+  @_Memo({ cacheKeyFn: intlCacheKeyFn })
   DurationFormat(
     locales: Intl.LocalesArgument,
     options: Intl.DurationFormatOptions,
@@ -46,7 +79,7 @@ class MemoizedIntl {
     return new Intl.DurationFormat(locales, options)
   }
 
-  @_Memo()
+  @_Memo({ cacheKeyFn: intlCacheKeyFn })
   NumberFormat(
     locales: Intl.LocalesArgument,
     options: Intl.NumberFormatOptions,
@@ -54,22 +87,22 @@ class MemoizedIntl {
     return new Intl.NumberFormat(locales, options)
   }
 
-  @_Memo()
+  @_Memo({ cacheKeyFn: intlCacheKeyFn })
   Collator(locales: Intl.LocalesArgument, options: Intl.CollatorOptions): Intl.Collator {
     return new Intl.Collator(locales, options)
   }
 
-  @_Memo()
+  @_Memo({ cacheKeyFn: intlCacheKeyFn })
   PluralRules(locales: Intl.LocalesArgument, options: Intl.PluralRulesOptions): Intl.PluralRules {
     return new Intl.PluralRules(locales, options)
   }
 
-  @_Memo()
+  @_Memo({ cacheKeyFn: intlCacheKeyFn })
   ListFormat(locales: Intl.LocalesArgument, options: Intl.ListFormatOptions): Intl.ListFormat {
     return new Intl.ListFormat(locales, options)
   }
 
-  @_Memo()
+  @_Memo({ cacheKeyFn: intlCacheKeyFn })
   DisplayNames(
     locales: Intl.LocalesArgument,
     options: Intl.DisplayNamesOptions,
@@ -77,10 +110,27 @@ class MemoizedIntl {
     return new Intl.DisplayNames(locales, options)
   }
 
-  @_Memo()
+  @_Memo({ cacheKeyFn: intlCacheKeyFn })
   Segmenter(locales: Intl.LocalesArgument, options: Intl.SegmenterOptions): Intl.Segmenter {
     return new Intl.Segmenter(locales, options)
   }
 }
 
 export const Intl2 = new MemoizedIntl()
+
+/**
+ * Default `jsonMemoSerializer` would serialize `Intl.Locale` instances as `{}`,
+ * making all Locale arguments share one cache key. Convert them to their string tags instead.
+ *
+ * Options keys are serialized in sorted order, so that `{ a, b }` and `{ b, a }` share one cache key.
+ * Passing a keys array as replacer works, because Intl options are flat objects.
+ */
+function intlCacheKeyFn([locales, options]: [Intl.LocalesArgument, AnyObject]): string {
+  return JSON.stringify(localesKey(locales)) + JSON.stringify(options, Object.keys(options).sort())
+}
+
+function localesKey(locales: Intl.LocalesArgument): string | string[] | undefined {
+  if (locales === undefined) return
+  if (Array.isArray(locales)) return locales.map(String)
+  return String(locales)
+}

package/src/semver.ts

@@ -20,6 +20,8 @@ export type SemverTokens = [major: number, minor: number, patch: number]
  *
  * _semver('1').toString() === '1.0.0'
  *
+ * 4-part strings are treated as equal to 3-part strings, e.g.: '1.2.3.4' === '1.2.3'
+ *
  * @experimental
  */
 export class Semver {