mazey 5.5.0 → 5.6.0

package/lib/index.d.ts

@@ -274,6 +274,188 @@ declare function isHit(rate: number): boolean;
  */
 declare function inRate(rate: number): boolean;
 
+/**
+ * Package managers supported by {@link derivePackageMetadata}.
+ *
+ * @category Util
+ */
+type PackageManager = "npm" | "pnpm" | "yarn";
+/**
+ * Author identity accepted from a package manifest.
+ *
+ * @category Util
+ */
+interface PackageManifestAuthor {
+    name: string;
+    email?: string;
+    url?: string;
+}
+/**
+ * Package manifest fields used by {@link derivePackageMetadata}.
+ *
+ * @category Util
+ */
+interface PackageManifest {
+    name: string;
+    version?: string;
+    description?: string;
+    license?: string;
+    author?: string | PackageManifestAuthor;
+}
+/**
+ * Options for {@link derivePackageMetadata}.
+ *
+ * @category Util
+ */
+interface DerivePackageMetadataOptions {
+    /** Package manager used in the generated install command. Defaults to `npm`. */
+    packageManager?: PackageManager;
+}
+/**
+ * Normalized package metadata derived from a package manifest.
+ *
+ * @category Util
+ */
+interface DerivedPackageMetadata {
+    name: string;
+    version?: string;
+    description?: string;
+    license?: string;
+    author: PackageManifestAuthor;
+    unscopedName: string;
+    iifeGlobal: string;
+    installCommand: string;
+}
+/**
+ * Validate basic package identity and derive reusable package metadata.
+ *
+ * The helper removes an npm scope for bundle naming, converts that unscoped
+ * name with {@link toJavaScriptGlobalName}, normalizes the supported author
+ * fields, and creates an install command for npm, pnpm, or Yarn.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { derivePackageMetadata } from "mazey";
+ *
+ * const metadata = derivePackageMetadata(
+ *   {
+ *     name: "@example/my-library",
+ *     version: "1.0.0",
+ *     author: { name: "Example Maintainer" },
+ *   },
+ *   { packageManager: "pnpm" }
+ * );
+ * console.log(metadata);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * {
+ *   name: "@example/my-library",
+ *   version: "1.0.0",
+ *   description: undefined,
+ *   license: undefined,
+ *   author: { name: "Example Maintainer" },
+ *   unscopedName: "my-library",
+ *   iifeGlobal: "MY_LIBRARY",
+ *   installCommand: "pnpm add @example/my-library"
+ * }
+ * ```
+ *
+ * @param manifest Package manifest identity fields. The package name is required.
+ * @param options Package-manager selection for the install command.
+ * @returns Normalized identity, bundle naming, and installation metadata.
+ * @throws {TypeError} If the manifest, package name, author, optional string fields, or package-manager option is invalid.
+ * @remarks The input manifest and nested author object are not mutated. This helper does not read files, environment variables, or package-manager configuration.
+ * @category Util
+ */
+declare function derivePackageMetadata(manifest: PackageManifest, options?: DerivePackageMetadataOptions): DerivedPackageMetadata;
+
+/**
+ * Precision used by `formatLocalDateTime`.
+ *
+ * @category Util
+ */
+type LocalDateTimePrecision = "minute" | "second" | "millisecond";
+/**
+ * Parse an HTML `datetime-local` value into a local `Date`.
+ *
+ * Accepted normalized values use a year with at least four digits followed by
+ * `-MM-DDTHH:mm`, with optional seconds and 1-3 fractional-second digits.
+ * Components are validated strictly, so impossible dates and times return
+ * `null` instead of being normalized by `Date`.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { parseLocalDateTime } from "mazey";
+ *
+ * const date = parseLocalDateTime("2026-07-21T14:30:45.123");
+ * console.log(date?.getFullYear());
+ * console.log(date?.getHours());
+ * console.log(date?.getMilliseconds());
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * 2026
+ * 14
+ * 123
+ * ```
+ *
+ * @param value A normalized HTML `datetime-local` value without a timezone.
+ * @returns A local `Date`, or `null` when the value is malformed or represents an impossible local date and time.
+ * @remarks The value is interpreted using the runtime's local timezone. Timezone suffixes, surrounding whitespace, and date-only values are rejected.
+ * @category Util
+ */
+declare function parseLocalDateTime(value: string): Date | null;
+/**
+ * Format a `Date` as an HTML `datetime-local` value using local fields.
+ *
+ * | Precision     | Output shape                  |
+ * | ------------- | ----------------------------- |
+ * | `minute`      | `YYYY-MM-DDTHH:mm`            |
+ * | `second`      | `YYYY-MM-DDTHH:mm:ss`         |
+ * | `millisecond` | `YYYY-MM-DDTHH:mm:ss.SSS`     |
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { formatLocalDateTime } from "mazey";
+ *
+ * const date = new Date(2026, 6, 21, 14, 30, 45, 123);
+ * const minutes = formatLocalDateTime(date);
+ * const seconds = formatLocalDateTime(date, { precision: "second" });
+ * const milliseconds = formatLocalDateTime(date, {
+ *   precision: "millisecond",
+ * });
+ * console.log(minutes);
+ * console.log(seconds);
+ * console.log(milliseconds);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * 2026-07-21T14:30
+ * 2026-07-21T14:30:45
+ * 2026-07-21T14:30:45.123
+ * ```
+ *
+ * @param date A valid `Date` to format.
+ * @param options Formatting options. Precision defaults to `minute`.
+ * @returns A normalized HTML `datetime-local` value containing local calendar fields. The year is padded to at least four digits.
+ * @throws {TypeError} If `date` is not a `Date` or `precision` is unsupported.
+ * @throws {RangeError} If `date` is invalid or its local year is earlier than 1.
+ * @remarks This function does not call `toISOString()` and does not convert the value to UTC. It does not mutate the supplied `Date`.
+ * @category Util
+ */
+declare function formatLocalDateTime(date: Date, options?: {
+    precision?: LocalDateTimePrecision;
+}): string;
 /**
  * Get the current timestamp in milliseconds.
  *
@@ -3592,6 +3774,99 @@ declare function genBrowserAttrs(prefix?: string, separator?: string): string[];
  * @category Browser Information
  */
 declare function isSupportWebp(): Promise<boolean>;
+/**
+ * Listen for media-query changes with modern and legacy browser APIs.
+ *
+ * Modern `addEventListener("change", ...)` support is preferred. Browsers
+ * exposing only `addListener` use that legacy API instead. A missing media
+ * query returns an inert cleanup function.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { listenMediaQueryChanges } from "mazey";
+ *
+ * const media = window.matchMedia("(prefers-color-scheme: dark)");
+ * const stop = listenMediaQueryChanges(media, event => {
+ *   console.log(event.matches);
+ * });
+ *
+ * stop();
+ * stop();
+ * ```
+ *
+ * @param media Media-query result to observe, or `null` when unavailable.
+ * @param listener Callback invoked for media-query change events.
+ * @returns An idempotent function that removes the registered listener.
+ * @throws {TypeError} If `listener` is not a function or `media` is neither an object nor `null`.
+ * @remarks This helper does not call `matchMedia`, invoke the listener immediately, or modify the DOM. It is safe during SSR when `null` is supplied.
+ * @category Browser Information
+ */
+declare function listenMediaQueryChanges(media: MediaQueryList | null, listener: (event: MediaQueryListEvent) => void): () => void;
+/**
+ * Callbacks used by {@link watchServiceWorkerUpdates}.
+ *
+ * @category Browser Information
+ */
+interface ServiceWorkerUpdateCallbacks {
+    /** Called when a waiting update is ready to be activated. */
+    onUpdateAvailable(worker: ServiceWorker): void;
+    /** Called after the service worker controlling the page changes. */
+    onControllerChange?(): void;
+}
+/**
+ * Controls returned by {@link watchServiceWorkerUpdates}.
+ *
+ * @category Browser Information
+ */
+interface ServiceWorkerUpdateWatcher {
+    /**
+     * Post a message to the current waiting worker.
+     * The default message is `{ type: "SKIP_WAITING" }`.
+     */
+    activateWaiting(message?: unknown): boolean;
+    /** Remove every listener installed by the watcher. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Watch a service-worker registration for an update ready to activate.
+ *
+ * Existing waiting workers and newly installed workers are reported only when
+ * the page already has a controller, which distinguishes updates from a first
+ * installation. Activation, UI, status copy, and reload policy remain under
+ * caller control.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { watchServiceWorkerUpdates } from "mazey";
+ *
+ * const watcher = watchServiceWorkerUpdates(
+ *   registration,
+ *   navigator.serviceWorker,
+ *   {
+ *     onUpdateAvailable() {
+ *       console.log("Update available");
+ *     },
+ *     onControllerChange() {
+ *       console.log("Controller changed");
+ *     },
+ *   }
+ * );
+ *
+ * watcher.activateWaiting();
+ * watcher.dispose();
+ * ```
+ *
+ * @param registration Service-worker registration to observe.
+ * @param container Service-worker container that owns the page controller.
+ * @param callbacks Update and optional controller-change callbacks.
+ * @returns Controls for requesting activation and disposing all listeners.
+ * @throws {TypeError} If required registration, container, or callback methods are missing.
+ * @remarks This helper does not register a service worker, mutate the DOM, reload the page, or decide when an update should activate. `activateWaiting` returns `false` when no update is waiting or `postMessage` fails.
+ * @category Browser Information
+ */
+declare function watchServiceWorkerUpdates(registration: ServiceWorkerRegistration, container: ServiceWorkerContainer, callbacks: ServiceWorkerUpdateCallbacks): ServiceWorkerUpdateWatcher;
 
 /**
  * A user-selectable color-theme preference.
@@ -3856,5 +4131,5 @@ declare const mazeyCon: Console;
  */
 declare const timeCon: Console;
 
-export { addClass, addEvent, addStyle, assignDefined, calLongestCommonSubsequence, calLongestCommonSubstring, calculateCAGR, camelCase2Underscore, camelCaseToKebabCase, cancelBubble, clearHTML, clearHtml, convert10To26, convertCamelToKebab, convertCamelToUnder, convertHttpToHttps, convertKebabToCamel, convertObjectToQuery, convertToHtmlBreaks, convertUnderToCamel, cutCHSString, cutZHString, debounce, deepCopy, deepCopyObject, deepFreeze, delCookie, detectVisitorType, doFn, extractElementText, fireEvent, floatFixed, floatToPercent, formatByteSize, formatDate, formatDistanceToNow, formatDurationFromMs, genBrowserAttrs, genCustomConsole, genHashCode, genRndNumString, genStyleString, genUniqueNumString, generateCalendarVersion, generateRndNum, generateUniqueNum, getAllQueryParams, getBrowserInfo, getCLS, getCookie, getCurrentVersion, getDateDifference, getDefineListeners, getDomain, getFCP, getFID, getFP, getFileSize, getFriendlyInterval, getHashQueryParam, getLCP, getLocalStorage, getPageMeta, getPerformance, getQueryParam, getScriptQueryParam, getSessionStorage, getTTFB, getUrlFileType, getUrlHost, getUrlParam, getUrlPath, hasClass, inRate, invokeEvent, invokeFn, isArray, isBool, isBoolean, isBrowser, isFunction, isHit, isJSONString, isJsonString, isNonEmptyArray, isNonEmptyObject, isNumber, isPureObject, isSafePWAEnv, isStandalonePWA, isString, isSupportWebp, isSupportedEntryType, isThisHour, isThisMonth, isThisWeek, isThisYear, isToday, isUdfOrNul, isValidCssSelector, isValidData, isValidDate, isValidEmail, isValidHttpUrl, isValidPhoneNumber, isValidUrl, loadCSS, loadImage, loadScript, loadScriptIfUndefined, longestComSubsequence, longestComSubstring, mNow, mTrim, mazeyCon, newLine, onURLChange, parseGitHubRepository, parseJsonSafe, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, resolveLanguagePreference, resolveThemePreference, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLanguagePreference, setLocalStorage, setSessionStorage, setThemePreference, sha256Hex, sleep, throttle, timeCon, toJavaScriptGlobalName, truncateZHString, unsanitize, unsanitizeInput, updateQueryParam, waitTime, windowLoaded, zAxiosIsValidRes };
-export type { FormatByteSizeOptions, GitHubRepositoryDetails, InvestmentReturnRate, IsSafePWAEnvOptions, PreferenceResult, ResolvedTheme, ThemePreference, VisitorType };
+export { addClass, addEvent, addStyle, assignDefined, calLongestCommonSubsequence, calLongestCommonSubstring, calculateCAGR, camelCase2Underscore, camelCaseToKebabCase, cancelBubble, clearHTML, clearHtml, convert10To26, convertCamelToKebab, convertCamelToUnder, convertHttpToHttps, convertKebabToCamel, convertObjectToQuery, convertToHtmlBreaks, convertUnderToCamel, cutCHSString, cutZHString, debounce, deepCopy, deepCopyObject, deepFreeze, delCookie, derivePackageMetadata, detectVisitorType, doFn, extractElementText, fireEvent, floatFixed, floatToPercent, formatByteSize, formatDate, formatDistanceToNow, formatDurationFromMs, formatLocalDateTime, genBrowserAttrs, genCustomConsole, genHashCode, genRndNumString, genStyleString, genUniqueNumString, generateCalendarVersion, generateRndNum, generateUniqueNum, getAllQueryParams, getBrowserInfo, getCLS, getCookie, getCurrentVersion, getDateDifference, getDefineListeners, getDomain, getFCP, getFID, getFP, getFileSize, getFriendlyInterval, getHashQueryParam, getLCP, getLocalStorage, getPageMeta, getPerformance, getQueryParam, getScriptQueryParam, getSessionStorage, getTTFB, getUrlFileType, getUrlHost, getUrlParam, getUrlPath, hasClass, inRate, invokeEvent, invokeFn, isArray, isBool, isBoolean, isBrowser, isFunction, isHit, isJSONString, isJsonString, isNonEmptyArray, isNonEmptyObject, isNumber, isPureObject, isSafePWAEnv, isStandalonePWA, isString, isSupportWebp, isSupportedEntryType, isThisHour, isThisMonth, isThisWeek, isThisYear, isToday, isUdfOrNul, isValidCssSelector, isValidData, isValidDate, isValidEmail, isValidHttpUrl, isValidPhoneNumber, isValidUrl, listenMediaQueryChanges, loadCSS, loadImage, loadScript, loadScriptIfUndefined, longestComSubsequence, longestComSubstring, mNow, mTrim, mazeyCon, newLine, onURLChange, parseGitHubRepository, parseJsonSafe, parseLocalDateTime, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, resolveLanguagePreference, resolveThemePreference, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLanguagePreference, setLocalStorage, setSessionStorage, setThemePreference, sha256Hex, sleep, throttle, timeCon, toJavaScriptGlobalName, truncateZHString, unsanitize, unsanitizeInput, updateQueryParam, waitTime, watchServiceWorkerUpdates, windowLoaded, zAxiosIsValidRes };
+export type { DerivePackageMetadataOptions, DerivedPackageMetadata, FormatByteSizeOptions, GitHubRepositoryDetails, InvestmentReturnRate, IsSafePWAEnvOptions, LocalDateTimePrecision, PackageManager, PackageManifest, PackageManifestAuthor, PreferenceResult, ResolvedTheme, ServiceWorkerUpdateCallbacks, ServiceWorkerUpdateWatcher, ThemePreference, VisitorType };