@naturalcycles/js-lib 14.95.0 → 14.96.1

package/dist/datetime/localDate.d.ts

@@ -24,8 +24,8 @@ export declare class LocalDate {
     /**
      * Returns null if invalid.
      */
-    static parseOrNull(d: LocalDateConfig): LocalDate | null;
-    static isValid(iso: string): boolean;
+    static parseOrNull(d: LocalDateConfig | undefined | null): LocalDate | null;
+    static isValid(iso: string | undefined | null): boolean;
     static today(): LocalDate;
     static todayUTC(): LocalDate;
     static sort(items: LocalDate[], mutate?: boolean, descending?: boolean): LocalDate[];

package/dist/datetime/localDate.js

@@ -46,6 +46,8 @@ class LocalDate {
      * Returns null if invalid.
      */
     static parseOrNull(d) {
+        if (!d)
+            return null;
         if (d instanceof LocalDate)
             return d;
         // todo: explore more performant options

package/dist/datetime/localTime.d.ts

@@ -27,8 +27,8 @@ export declare class LocalTime {
     /**
      * Returns null if invalid
      */
-    static parseOrNull(d: LocalTimeConfig): LocalTime | null;
-    static isValid(d: LocalTimeConfig): boolean;
+    static parseOrNull(d: LocalTimeConfig | undefined | null): LocalTime | null;
+    static isValid(d: LocalTimeConfig | undefined | null): boolean;
     static now(): LocalTime;
     static fromComponents(c: {
         year: number;

package/dist/datetime/localTime.js

@@ -5,18 +5,6 @@ const assert_1 = require("../error/assert");
 const time_util_1 = require("../time/time.util");
 const localDate_1 = require("./localDate");
 /* eslint-disable no-dupe-class-members */
-// Design choices:
-// No milliseconds
-// No timezone support, ISO8601 is parsed as LocalDateTime, discarding Timezone information
-// Formats as unix timestamp, ISO8601 or "pretty string"
-// toString and .toJSON formats as unix timestamp
-// No "unixMillis", just pure unixtimestamp
-// .valueOf returns unix timestamp (no millis)
-// Prevents dayjs(undefined) being dayjs.now()
-// Validates on parse, throws if invalid. Doesn't allow invalid objects
-// No arbitrary .format('') (which is slow to parse) vs well-defined (opinionated) formats
-// Separate LocalTime, powered by native js Date, and LocalDate - a smaller functionality class when
-// you only need "whole dates", no time, no timezone worry
 /**
  * @experimental
  */
@@ -48,6 +36,8 @@ class LocalTime {
      * Returns null if invalid
      */
     static parseOrNull(d) {
+        if (!d)
+            return null;
         if (d instanceof LocalTime)
             return d;
         let date;

package/dist/decorators/debounce.js

@@ -10,7 +10,7 @@ function _debounce(func, wait, opt = {}) {
     let lastInvokeTime = 0;
     const maxing = 'maxWait' in opt;
     const { leading = false, trailing = true } = opt;
-    const maxWait = maxing ? Math.max(+opt.maxWait || 0, wait) : opt.maxWait;
+    const maxWait = maxing ? Math.max(Number(opt.maxWait) || 0, wait) : opt.maxWait;
     function invokeFunc(time) {
         const args = lastArgs;
         const thisArg = lastThis;

package/dist/error/try.d.ts

@@ -5,25 +5,31 @@ import { AppError } from './app.error';
  * Allows to write shorter code that avoids `try/catch`.
  * Useful e.g. in unit tests.
  *
- * Similar to pTuple, but for sync functions.
+ * Similar to pTry, but for sync functions.
  *
  * For convenience, second argument type is non-optional,
  * so you can use it without `!`. But you SHOULD always check `if (err)` first!
  *
+ * ERR is typed as Error, not `unknown`. While unknown would be more correct,
+ * according to recent TypeScript, Error gives more developer convenience.
+ * In our code we NEVER throw non-errors.
+ * Only possibility of non-error is in the 3rd-party library code, in these cases it
+ * can be manually cast to `unknown` for extra safety.
+ *
  * @example
  *
  * const [err, v] = _try(() => someFunction())
  * if (err) ...do something...
  * v // go ahead and use v
  */
-export declare function _try<ERR = unknown, RETURN = void>(fn: () => RETURN): [err: ERR | null, value: RETURN];
+export declare function _try<ERR = Error, RETURN = void>(fn: () => RETURN): [err: ERR | null, value: RETURN];
 /**
  * Like _try, but for Promises.
  *
  * Also, intentionally types second return item as non-optional,
  * but you should check for `err` presense first!
  */
-export declare function pTry<ERR = unknown, RETURN = void>(promise: Promise<RETURN>): Promise<[err: ERR | null, value: Awaited<RETURN>]>;
+export declare function pTry<ERR = Error, RETURN = void>(promise: Promise<RETURN>): Promise<[err: ERR | null, value: Awaited<RETURN>]>;
 /**
  * It is thrown when Error was expected, but didn't happen
  * ("pass" happened instead).

package/dist/error/try.js

@@ -7,11 +7,17 @@ const app_error_1 = require("./app.error");
  * Allows to write shorter code that avoids `try/catch`.
  * Useful e.g. in unit tests.
  *
- * Similar to pTuple, but for sync functions.
+ * Similar to pTry, but for sync functions.
  *
  * For convenience, second argument type is non-optional,
  * so you can use it without `!`. But you SHOULD always check `if (err)` first!
  *
+ * ERR is typed as Error, not `unknown`. While unknown would be more correct,
+ * according to recent TypeScript, Error gives more developer convenience.
+ * In our code we NEVER throw non-errors.
+ * Only possibility of non-error is in the 3rd-party library code, in these cases it
+ * can be manually cast to `unknown` for extra safety.
+ *
  * @example
  *
  * const [err, v] = _try(() => someFunction())
@@ -49,7 +55,7 @@ exports.pTry = pTry;
  */
 class UnexpectedPassError extends app_error_1.AppError {
     constructor() {
-        super('_expectedError passed unexpectedly');
+        super('expected error was not thrown');
     }
 }
 exports.UnexpectedPassError = UnexpectedPassError;

package/dist/error/tryCatch.d.ts

@@ -5,7 +5,7 @@ export interface TryCatchOptions {
      * The value returned from the function will be returned from the wrapped method (!).
      * onError function may be asynchronous.
      */
-    onError?: (err: unknown) => any;
+    onError?: (err: Error) => any;
     /**
      * @default false
      */

package/dist/error/tryCatch.js

@@ -30,7 +30,7 @@ function _tryCatch(fn, opt = {}) {
             }
             if (onError) {
                 try {
-                    return await onError(err); // eslint-disable-line @typescript-eslint/return-await
+                    return await onError((0, index_1._anyToError)(err)); // eslint-disable-line @typescript-eslint/return-await
                 }
                 catch { }
             }

package/dist/index.d.ts

@@ -45,7 +45,6 @@ export * from './promise/pProps';
 import { pRetry, pRetryFn, PRetryOptions } from './promise/pRetry';
 export * from './promise/pState';
 import { pTimeout, pTimeoutFn, PTimeoutOptions } from './promise/pTimeout';
-export * from './promise/pTuple';
 export * from './string/case';
 export * from './string/json.util';
 export * from './string/string.util';

package/dist/index.js

@@ -59,7 +59,6 @@ tslib_1.__exportStar(require("./promise/pState"), exports);
 const pTimeout_1 = require("./promise/pTimeout");
 Object.defineProperty(exports, "pTimeout", { enumerable: true, get: function () { return pTimeout_1.pTimeout; } });
 Object.defineProperty(exports, "pTimeoutFn", { enumerable: true, get: function () { return pTimeout_1.pTimeoutFn; } });
-tslib_1.__exportStar(require("./promise/pTuple"), exports);
 tslib_1.__exportStar(require("./string/case"), exports);
 tslib_1.__exportStar(require("./string/json.util"), exports);
 tslib_1.__exportStar(require("./string/string.util"), exports);

package/dist/string/safeJsonStringify.js

@@ -17,7 +17,7 @@ function _safeJsonStringify(obj, replacer, spaces, cycleReplacer) {
     }
 }
 exports._safeJsonStringify = _safeJsonStringify;
-/* eslint-disable @typescript-eslint/no-unused-expressions, no-bitwise */
+/* eslint-disable @typescript-eslint/no-unused-expressions, no-bitwise, no-implicit-coercion */
 function serializer(replacer, cycleReplacer) {
     const stack = [];
     const keys = [];

package/dist-esm/datetime/localDate.js

@@ -43,6 +43,8 @@ export class LocalDate {
      * Returns null if invalid.
      */
     static parseOrNull(d) {
+        if (!d)
+            return null;
         if (d instanceof LocalDate)
             return d;
         // todo: explore more performant options

package/dist-esm/datetime/localTime.js

@@ -2,18 +2,6 @@ import { _assert } from '../error/assert';
 import { _ms } from '../time/time.util';
 import { LocalDate } from './localDate';
 /* eslint-disable no-dupe-class-members */
-// Design choices:
-// No milliseconds
-// No timezone support, ISO8601 is parsed as LocalDateTime, discarding Timezone information
-// Formats as unix timestamp, ISO8601 or "pretty string"
-// toString and .toJSON formats as unix timestamp
-// No "unixMillis", just pure unixtimestamp
-// .valueOf returns unix timestamp (no millis)
-// Prevents dayjs(undefined) being dayjs.now()
-// Validates on parse, throws if invalid. Doesn't allow invalid objects
-// No arbitrary .format('') (which is slow to parse) vs well-defined (opinionated) formats
-// Separate LocalTime, powered by native js Date, and LocalDate - a smaller functionality class when
-// you only need "whole dates", no time, no timezone worry
 /**
  * @experimental
  */
@@ -45,6 +33,8 @@ export class LocalTime {
      * Returns null if invalid
      */
     static parseOrNull(d) {
+        if (!d)
+            return null;
         if (d instanceof LocalTime)
             return d;
         let date;

package/dist-esm/decorators/debounce.js

@@ -7,7 +7,7 @@ export function _debounce(func, wait, opt = {}) {
     let lastInvokeTime = 0;
     const maxing = 'maxWait' in opt;
     const { leading = false, trailing = true } = opt;
-    const maxWait = maxing ? Math.max(+opt.maxWait || 0, wait) : opt.maxWait;
+    const maxWait = maxing ? Math.max(Number(opt.maxWait) || 0, wait) : opt.maxWait;
     function invokeFunc(time) {
         const args = lastArgs;
         const thisArg = lastThis;

package/dist-esm/error/try.js

@@ -4,11 +4,17 @@ import { AppError } from './app.error';
  * Allows to write shorter code that avoids `try/catch`.
  * Useful e.g. in unit tests.
  *
- * Similar to pTuple, but for sync functions.
+ * Similar to pTry, but for sync functions.
  *
  * For convenience, second argument type is non-optional,
  * so you can use it without `!`. But you SHOULD always check `if (err)` first!
  *
+ * ERR is typed as Error, not `unknown`. While unknown would be more correct,
+ * according to recent TypeScript, Error gives more developer convenience.
+ * In our code we NEVER throw non-errors.
+ * Only possibility of non-error is in the 3rd-party library code, in these cases it
+ * can be manually cast to `unknown` for extra safety.
+ *
  * @example
  *
  * const [err, v] = _try(() => someFunction())
@@ -44,7 +50,7 @@ export async function pTry(promise) {
  */
 export class UnexpectedPassError extends AppError {
     constructor() {
-        super('_expectedError passed unexpectedly');
+        super('expected error was not thrown');
     }
 }
 /**

package/dist-esm/error/tryCatch.js

@@ -1,4 +1,4 @@
-import { _since, _stringifyAny } from '../index';
+import { _anyToError, _since, _stringifyAny } from '../index';
 /**
  * Decorates a function with "try/catch", so it'll never reject/throw.
  * Only applies to async functions (or, turns sync function into async).
@@ -27,7 +27,7 @@ export function _tryCatch(fn, opt = {}) {
             }
             if (onError) {
                 try {
-                    return await onError(err); // eslint-disable-line @typescript-eslint/return-await
+                    return await onError(_anyToError(err)); // eslint-disable-line @typescript-eslint/return-await
                 }
                 catch (_a) { }
             }

package/dist-esm/index.js

@@ -42,7 +42,6 @@ export * from './promise/pProps';
 import { pRetry, pRetryFn } from './promise/pRetry';
 export * from './promise/pState';
 import { pTimeout, pTimeoutFn } from './promise/pTimeout';
-export * from './promise/pTuple';
 export * from './string/case';
 export * from './string/json.util';
 export * from './string/string.util';

package/dist-esm/string/safeJsonStringify.js

@@ -13,7 +13,7 @@ export function _safeJsonStringify(obj, replacer, spaces, cycleReplacer) {
         return JSON.stringify(obj, serializer(replacer, cycleReplacer), spaces);
     }
 }
-/* eslint-disable @typescript-eslint/no-unused-expressions, no-bitwise */
+/* eslint-disable @typescript-eslint/no-unused-expressions, no-bitwise, no-implicit-coercion */
 function serializer(replacer, cycleReplacer) {
     const stack = [];
     const keys = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.95.0",
+  "version": "14.96.1",
   "scripts": {
     "prepare": "husky install",
     "build-prod": "build-prod-esm-cjs",

package/src/datetime/localDate.ts

@@ -55,7 +55,8 @@ export class LocalDate {
   /**
    * Returns null if invalid.
    */
-  static parseOrNull(d: LocalDateConfig): LocalDate | null {
+  static parseOrNull(d: LocalDateConfig | undefined | null): LocalDate | null {
+    if (!d) return null
     if (d instanceof LocalDate) return d
 
     // todo: explore more performant options
@@ -76,7 +77,7 @@ export class LocalDate {
     return new LocalDate(year, month, day)
   }
 
-  static isValid(iso: string): boolean {
+  static isValid(iso: string | undefined | null): boolean {
     return this.parseOrNull(iso) !== null
   }
 

package/src/datetime/localTime.ts

@@ -18,18 +18,6 @@ export interface LocalTimeComponents {
 
 /* eslint-disable no-dupe-class-members */
 
-// Design choices:
-// No milliseconds
-// No timezone support, ISO8601 is parsed as LocalDateTime, discarding Timezone information
-// Formats as unix timestamp, ISO8601 or "pretty string"
-// toString and .toJSON formats as unix timestamp
-// No "unixMillis", just pure unixtimestamp
-// .valueOf returns unix timestamp (no millis)
-// Prevents dayjs(undefined) being dayjs.now()
-// Validates on parse, throws if invalid. Doesn't allow invalid objects
-// No arbitrary .format('') (which is slow to parse) vs well-defined (opinionated) formats
-// Separate LocalTime, powered by native js Date, and LocalDate - a smaller functionality class when
-// you only need "whole dates", no time, no timezone worry
 /**
  * @experimental
  */
@@ -63,7 +51,8 @@ export class LocalTime {
   /**
    * Returns null if invalid
    */
-  static parseOrNull(d: LocalTimeConfig): LocalTime | null {
+  static parseOrNull(d: LocalTimeConfig | undefined | null): LocalTime | null {
+    if (!d) return null
     if (d instanceof LocalTime) return d
 
     let date
@@ -89,7 +78,7 @@ export class LocalTime {
     return new LocalTime(date, false)
   }
 
-  static isValid(d: LocalTimeConfig): boolean {
+  static isValid(d: LocalTimeConfig | undefined | null): boolean {
     return this.parseOrNull(d) !== null
   }
 

package/src/decorators/debounce.ts

@@ -49,7 +49,7 @@ export function _debounce<T extends AnyFunction>(
   const maxing = 'maxWait' in opt
 
   const { leading = false, trailing = true } = opt
-  const maxWait = maxing ? Math.max(+opt.maxWait! || 0, wait) : opt.maxWait
+  const maxWait = maxing ? Math.max(Number(opt.maxWait) || 0, wait) : opt.maxWait
 
   function invokeFunc(time: number) {
     const args = lastArgs

package/src/error/try.ts

@@ -6,18 +6,24 @@ import { AppError } from './app.error'
  * Allows to write shorter code that avoids `try/catch`.
  * Useful e.g. in unit tests.
  *
- * Similar to pTuple, but for sync functions.
+ * Similar to pTry, but for sync functions.
  *
  * For convenience, second argument type is non-optional,
  * so you can use it without `!`. But you SHOULD always check `if (err)` first!
  *
+ * ERR is typed as Error, not `unknown`. While unknown would be more correct,
+ * according to recent TypeScript, Error gives more developer convenience.
+ * In our code we NEVER throw non-errors.
+ * Only possibility of non-error is in the 3rd-party library code, in these cases it
+ * can be manually cast to `unknown` for extra safety.
+ *
  * @example
  *
  * const [err, v] = _try(() => someFunction())
  * if (err) ...do something...
  * v // go ahead and use v
  */
-export function _try<ERR = unknown, RETURN = void>(
+export function _try<ERR = Error, RETURN = void>(
   fn: () => RETURN,
 ): [err: ERR | null, value: RETURN] {
   try {
@@ -33,7 +39,7 @@ export function _try<ERR = unknown, RETURN = void>(
  * Also, intentionally types second return item as non-optional,
  * but you should check for `err` presense first!
  */
-export async function pTry<ERR = unknown, RETURN = void>(
+export async function pTry<ERR = Error, RETURN = void>(
   promise: Promise<RETURN>,
 ): Promise<[err: ERR | null, value: Awaited<RETURN>]> {
   try {
@@ -50,7 +56,7 @@ export async function pTry<ERR = unknown, RETURN = void>(
  */
 export class UnexpectedPassError extends AppError {
   constructor() {
-    super('_expectedError passed unexpectedly')
+    super('expected error was not thrown')
   }
 }
 

package/src/error/tryCatch.ts

@@ -1,4 +1,4 @@
-import { _since, _stringifyAny, CommonLogger } from '../index'
+import { _anyToError, _since, _stringifyAny, CommonLogger } from '../index'
 import { AnyFunction } from '../types'
 
 export interface TryCatchOptions {
@@ -6,7 +6,7 @@ export interface TryCatchOptions {
    * The value returned from the function will be returned from the wrapped method (!).
    * onError function may be asynchronous.
    */
-  onError?: (err: unknown) => any
+  onError?: (err: Error) => any
 
   /**
    * @default false
@@ -59,7 +59,7 @@ export function _tryCatch<T extends AnyFunction>(fn: T, opt: TryCatchOptions = {
 
       if (onError) {
         try {
-          return await onError(err) // eslint-disable-line @typescript-eslint/return-await
+          return await onError(_anyToError(err)) // eslint-disable-line @typescript-eslint/return-await
         } catch {}
       }
       // returns undefined, but doesn't rethrow

package/src/index.ts

@@ -78,7 +78,6 @@ export * from './promise/pProps'
 import { pRetry, pRetryFn, PRetryOptions } from './promise/pRetry'
 export * from './promise/pState'
 import { pTimeout, pTimeoutFn, PTimeoutOptions } from './promise/pTimeout'
-export * from './promise/pTuple'
 export * from './string/case'
 export * from './string/json.util'
 export * from './string/string.util'

package/src/string/safeJsonStringify.ts

@@ -20,7 +20,7 @@ export function _safeJsonStringify(
   }
 }
 
-/* eslint-disable @typescript-eslint/no-unused-expressions, no-bitwise */
+/* eslint-disable @typescript-eslint/no-unused-expressions, no-bitwise, no-implicit-coercion */
 
 function serializer(replacer?: Reviver, cycleReplacer?: Reviver): Reviver {
   const stack: any[] = []

package/dist/promise/pTuple.d.ts

@@ -1,7 +0,0 @@
-/**
- * Wraps async calls in try catch blocks
- * to simplify syntax.
- *
- * source: https://github.com/scopsy/await-to-js/blob/master/src/await-to-js.ts
- */
-export declare function pTuple<RETURN, ERR = Error>(promise: Promise<RETURN>): Promise<[ERR, undefined] | [null, RETURN]>;

package/dist/promise/pTuple.js

@@ -1,13 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pTuple = void 0;
-/**
- * Wraps async calls in try catch blocks
- * to simplify syntax.
- *
- * source: https://github.com/scopsy/await-to-js/blob/master/src/await-to-js.ts
- */
-async function pTuple(promise) {
-    return promise.then(data => [null, data]).catch(err => [err, undefined]);
-}
-exports.pTuple = pTuple;

package/dist-esm/promise/pTuple.js

@@ -1,9 +0,0 @@
-/**
- * Wraps async calls in try catch blocks
- * to simplify syntax.
- *
- * source: https://github.com/scopsy/await-to-js/blob/master/src/await-to-js.ts
- */
-export async function pTuple(promise) {
-    return promise.then(data => [null, data]).catch(err => [err, undefined]);
-}

package/src/promise/pTuple.ts

@@ -1,11 +0,0 @@
-/**
- * Wraps async calls in try catch blocks
- * to simplify syntax.
- *
- * source: https://github.com/scopsy/await-to-js/blob/master/src/await-to-js.ts
- */
-export async function pTuple<RETURN, ERR = Error>(
-  promise: Promise<RETURN>,
-): Promise<[ERR, undefined] | [null, RETURN]> {
-  return promise.then(data => [null, data] as [null, RETURN]).catch(err => [err as ERR, undefined])
-}