@naturalcycles/js-lib 14.104.2 → 14.105.0

package/dist/enum.util.d.ts

@@ -0,0 +1,55 @@
+import { NumberEnum, StringEnum } from './types';
+/**
+ * Returns all number keys of a number-enum.
+ */
+export declare function _numberEnumKeys(en: NumberEnum): string[];
+/**
+ * Returns all number values of a number-enum.
+ */
+export declare function _numberEnumValues(en: NumberEnum): number[];
+/**
+ * Returns all string keys of a string-enum.
+ */
+export declare function _stringEnumKeys(en: StringEnum): string[];
+/**
+ * Returns all string values of a string-enum.
+ */
+export declare function _stringEnumValues(en: StringEnum): string[];
+/**
+ * Returns all number-enum "entries", where entry is a tuple of [key, value],
+ * where key is a String key, value is a Number value, typed as Enum itself.
+ *
+ * Doesn't work on String-enums!
+ */
+export declare function _numberEnumEntries<T extends NumberEnum>(en: T): [k: string, v: T[keyof T]][];
+/**
+ * Returns all string-enum "entries", where entry is a tuple of [key, value],
+ * where key is a String key, value is a String value, typed as Enum itself.
+ *
+ * Doesn't work on Number-enums!
+ */
+export declare function _stringEnumEntries<T extends StringEnum>(en: T): [k: string, v: T[keyof T]][];
+/**
+ * Allows to return a Number enum value (typed as Enum itself) based on it's String key.
+ * e.g:
+ * const v = SomeEnum['stringValue']
+ * // v is of type SomeEnum, which is of type Number
+ *
+ * Throws if value is not found!
+ */
+export declare function _numberEnumInverse<T extends NumberEnum>(en: T, v: string): T[keyof T];
+/**
+ * _enumInverse, but allows to get/return undefined output.
+ */
+export declare function _numberEnumInverseNullable<T extends NumberEnum>(en: T, v: string | undefined): T[keyof T] | undefined;
+/**
+ * Takes number or string enum input, returns normalized Enum output.
+ * Only works for number enums.
+ *
+ * Throws if value is not found!
+ */
+export declare function _numberEnumNormalize<T extends NumberEnum>(en: T, v: string | number): T[keyof T];
+/**
+ * Same as _enumNormalize, but allows to return undefined values.
+ */
+export declare function _numberEnumNormalizeNullable<T extends NumberEnum>(en: T, v: string | number | undefined): T[keyof T] | undefined;

package/dist/enum.util.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._numberEnumNormalizeNullable = exports._numberEnumNormalize = exports._numberEnumInverseNullable = exports._numberEnumInverse = exports._stringEnumEntries = exports._numberEnumEntries = exports._stringEnumValues = exports._stringEnumKeys = exports._numberEnumValues = exports._numberEnumKeys = void 0;
+/**
+ * Returns all number keys of a number-enum.
+ */
+function _numberEnumKeys(en) {
+    return Object.values(en).filter(k => typeof k === 'string');
+}
+exports._numberEnumKeys = _numberEnumKeys;
+/**
+ * Returns all number values of a number-enum.
+ */
+function _numberEnumValues(en) {
+    return Object.values(en).filter(k => typeof k === 'number');
+}
+exports._numberEnumValues = _numberEnumValues;
+/**
+ * Returns all string keys of a string-enum.
+ */
+function _stringEnumKeys(en) {
+    return Object.keys(en);
+}
+exports._stringEnumKeys = _stringEnumKeys;
+/**
+ * Returns all string values of a string-enum.
+ */
+function _stringEnumValues(en) {
+    // filtering here is unnecessary, but works as a safety in case Number-enum is passed
+    return Object.values(en).filter(k => typeof k === 'string');
+}
+exports._stringEnumValues = _stringEnumValues;
+/**
+ * Returns all number-enum "entries", where entry is a tuple of [key, value],
+ * where key is a String key, value is a Number value, typed as Enum itself.
+ *
+ * Doesn't work on String-enums!
+ */
+function _numberEnumEntries(en) {
+    return Object.values(en)
+        .filter(k => typeof k === 'string')
+        .map(k => [k, en[k]]);
+}
+exports._numberEnumEntries = _numberEnumEntries;
+/**
+ * Returns all string-enum "entries", where entry is a tuple of [key, value],
+ * where key is a String key, value is a String value, typed as Enum itself.
+ *
+ * Doesn't work on Number-enums!
+ */
+function _stringEnumEntries(en) {
+    return Object.keys(en).map(k => [k, en[k]]);
+}
+exports._stringEnumEntries = _stringEnumEntries;
+/**
+ * Allows to return a Number enum value (typed as Enum itself) based on it's String key.
+ * e.g:
+ * const v = SomeEnum['stringValue']
+ * // v is of type SomeEnum, which is of type Number
+ *
+ * Throws if value is not found!
+ */
+function _numberEnumInverse(en, v) {
+    const r = en[v];
+    if (!r)
+        throw new Error(`enumInverse value not found for: ${v}`);
+    return r;
+}
+exports._numberEnumInverse = _numberEnumInverse;
+/**
+ * _enumInverse, but allows to get/return undefined output.
+ */
+function _numberEnumInverseNullable(en, v) {
+    return en[v];
+}
+exports._numberEnumInverseNullable = _numberEnumInverseNullable;
+/**
+ * Takes number or string enum input, returns normalized Enum output.
+ * Only works for number enums.
+ *
+ * Throws if value is not found!
+ */
+function _numberEnumNormalize(en, v) {
+    const r = _numberEnumNormalizeNullable(en, v);
+    if (!r || !en[r])
+        throw new Error(`enumNormalize value not found for: ${v}`);
+    return r;
+}
+exports._numberEnumNormalize = _numberEnumNormalize;
+/**
+ * Same as _enumNormalize, but allows to return undefined values.
+ */
+function _numberEnumNormalizeNullable(en, v) {
+    return typeof v === 'string' ? en[v] : v;
+}
+exports._numberEnumNormalizeNullable = _numberEnumNormalizeNullable;

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export * from './decorators/retry.decorator';
 export * from './decorators/timeout.decorator';
 export * from './error/app.error';
 export * from './error/assert';
+export * from './enum.util';
 import { Admin401ErrorData, Admin403ErrorData, ErrorData, ErrorObject, HttpErrorData, HttpErrorResponse } from './error/error.model';
 export * from './error/error.util';
 import { ErrorMode } from './error/errorMode';
@@ -52,7 +53,7 @@ import { JsonStringifyFunction, StringifyAnyOptions, _stringifyAny } from './str
 export * from './time/time.util';
 export * from './is.util';
 import { Class, ConditionalExcept, ConditionalPick, Merge, Promisable, ReadonlyDeep, Simplify } from './typeFest';
-import { AsyncMapper, AsyncPredicate, BaseDBEntity, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, Saved, Unsaved, UnsavedId, BatchResult, InstanceId, IsoDate, IsoDateString, IsoDateTimeString, KeyValueTuple, Mapper, ObjectMapper, ObjectPredicate, Predicate, PromiseMap, AnyObject, AnyFunction, Reviver, SavedDBEntity, StringMap, UnixTimestampNumber, UnixTimestampMillisNumber, UnixTimestamp, Integer, ValueOf, ValuesOf, AbortableMapper, AbortableAsyncPredicate, AbortableAsyncMapper, AbortablePredicate, NullishValue, FalsyValue, END, SKIP, _noop, _objectKeys, _passNothingPredicate, _passthroughMapper, _passthroughPredicate, _passUndefinedMapper, _stringMapEntries, _stringMapValues } from './types';
+import { AsyncMapper, AsyncPredicate, BaseDBEntity, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, Saved, Unsaved, UnsavedId, BatchResult, InstanceId, IsoDate, IsoDateString, IsoDateTimeString, KeyValueTuple, Mapper, ObjectMapper, ObjectPredicate, Predicate, PromiseMap, AnyObject, AnyEnum, NumberEnum, StringEnum, AnyFunction, Reviver, SavedDBEntity, StringMap, UnixTimestampNumber, UnixTimestampMillisNumber, UnixTimestamp, Integer, ValueOf, ValuesOf, AbortableMapper, AbortableAsyncPredicate, AbortableAsyncMapper, AbortablePredicate, NullishValue, FalsyValue, END, SKIP, _noop, _objectKeys, _passNothingPredicate, _passthroughMapper, _passthroughPredicate, _passUndefinedMapper, _stringMapEntries, _stringMapValues } from './types';
 export * from './unit/size.util';
 import { is } from './vendor/is';
 import { CommonLogLevel, CommonLogFunction, CommonLogger, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, CommonLogWithLevelFunction, commonLoggerCreate } from './log/commonLogger';
@@ -69,5 +70,5 @@ import { LocalDateConfig, LocalDateFormatter, LocalDateUnit, LocalDateUnitStrict
 import { LocalTimeConfig, LocalTimeFormatter, LocalTimeUnit, LocalTimeComponents, ISODayOfWeek } from './datetime/localTime';
 import { DateIntervalConfig, DateIntervalString } from './datetime/dateInterval';
 import { TimeIntervalConfig, TimeIntervalString } from './datetime/timeInterval';
-export type { DateIntervalConfig, DateIntervalString, TimeIntervalConfig, TimeIntervalString, LocalDateConfig, LocalDateFormatter, LocalDateUnit, LocalDateUnitStrict, Inclusiveness, LocalTimeConfig, LocalTimeFormatter, LocalTimeUnit, ISODayOfWeek, LocalTimeComponents, AbortableMapper, AbortablePredicate, AbortableAsyncPredicate, AbortableAsyncMapper, PQueueCfg, MemoCache, AsyncMemoCache, PromiseDecoratorCfg, PromiseDecoratorResp, ErrorData, ErrorObject, HttpErrorData, HttpErrorResponse, Admin401ErrorData, Admin403ErrorData, StringMap, PromiseMap, AnyObject, AnyFunction, ValuesOf, ValueOf, KeyValueTuple, ObjectMapper, ObjectPredicate, InstanceId, IsoDate, IsoDateString, IsoDateTimeString, Reviver, FalsyValue, NullishValue, PMapOptions, Mapper, AsyncMapper, Predicate, AsyncPredicate, BatchResult, DeferredPromise, PRetryOptions, PTimeoutOptions, TryCatchOptions, StringifyAnyOptions, JsonStringifyFunction, Merge, ReadonlyDeep, Promisable, Simplify, ConditionalPick, ConditionalExcept, Class, UnixTimestampNumber, UnixTimestampMillisNumber, UnixTimestamp, Integer, BaseDBEntity, SavedDBEntity, Saved, Unsaved, UnsavedId, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, JsonSchema, JsonSchemaAny, JsonSchemaOneOf, JsonSchemaAllOf, JsonSchemaAnyOf, JsonSchemaNot, JsonSchemaRef, JsonSchemaConst, JsonSchemaEnum, JsonSchemaString, JsonSchemaNumber, JsonSchemaBoolean, JsonSchemaNull, JsonSchemaRootObject, JsonSchemaObject, JsonSchemaArray, JsonSchemaTuple, JsonSchemaBuilder, CommonLogLevel, CommonLogWithLevelFunction, CommonLogFunction, CommonLogger, };
+export type { DateIntervalConfig, DateIntervalString, TimeIntervalConfig, TimeIntervalString, LocalDateConfig, LocalDateFormatter, LocalDateUnit, LocalDateUnitStrict, Inclusiveness, LocalTimeConfig, LocalTimeFormatter, LocalTimeUnit, ISODayOfWeek, LocalTimeComponents, AbortableMapper, AbortablePredicate, AbortableAsyncPredicate, AbortableAsyncMapper, PQueueCfg, MemoCache, AsyncMemoCache, PromiseDecoratorCfg, PromiseDecoratorResp, ErrorData, ErrorObject, HttpErrorData, HttpErrorResponse, Admin401ErrorData, Admin403ErrorData, StringMap, PromiseMap, AnyObject, AnyEnum, NumberEnum, StringEnum, AnyFunction, ValuesOf, ValueOf, KeyValueTuple, ObjectMapper, ObjectPredicate, InstanceId, IsoDate, IsoDateString, IsoDateTimeString, Reviver, FalsyValue, NullishValue, PMapOptions, Mapper, AsyncMapper, Predicate, AsyncPredicate, BatchResult, DeferredPromise, PRetryOptions, PTimeoutOptions, TryCatchOptions, StringifyAnyOptions, JsonStringifyFunction, Merge, ReadonlyDeep, Promisable, Simplify, ConditionalPick, ConditionalExcept, Class, UnixTimestampNumber, UnixTimestampMillisNumber, UnixTimestamp, Integer, BaseDBEntity, SavedDBEntity, Saved, Unsaved, UnsavedId, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, JsonSchema, JsonSchemaAny, JsonSchemaOneOf, JsonSchemaAllOf, JsonSchemaAnyOf, JsonSchemaNot, JsonSchemaRef, JsonSchemaConst, JsonSchemaEnum, JsonSchemaString, JsonSchemaNumber, JsonSchemaBoolean, JsonSchemaNull, JsonSchemaRootObject, JsonSchemaObject, JsonSchemaArray, JsonSchemaTuple, JsonSchemaBuilder, CommonLogLevel, CommonLogWithLevelFunction, CommonLogFunction, CommonLogger, };
 export { is, _createPromiseDecorator, _stringMapValues, _stringMapEntries, _objectKeys, pMap, _passthroughMapper, _passUndefinedMapper, _passthroughPredicate, _passNothingPredicate, _noop, ErrorMode, pDefer, AggregatedError, pRetry, pRetryFn, pTimeout, pTimeoutFn, _tryCatch, _TryCatch, _stringifyAny, jsonSchema, JsonSchemaAnyBuilder, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, commonLoggerCreate, PQueue, END, SKIP, };

package/dist/index.js

@@ -20,6 +20,7 @@ tslib_1.__exportStar(require("./decorators/retry.decorator"), exports);
 tslib_1.__exportStar(require("./decorators/timeout.decorator"), exports);
 tslib_1.__exportStar(require("./error/app.error"), exports);
 tslib_1.__exportStar(require("./error/assert"), exports);
+tslib_1.__exportStar(require("./enum.util"), exports);
 tslib_1.__exportStar(require("./error/error.util"), exports);
 const errorMode_1 = require("./error/errorMode");
 Object.defineProperty(exports, "ErrorMode", { enumerable: true, get: function () { return errorMode_1.ErrorMode; } });

package/dist/types.d.ts

@@ -20,6 +20,9 @@ export interface PromiseMap {
  * Because `object` type is not safe/recommended to be used (e.g discouraged by eslint-typescript due to: https://github.com/microsoft/TypeScript/issues/21732)
  */
 export declare type AnyObject = Record<string, any>;
+export declare type AnyEnum = NumberEnum;
+export declare type NumberEnum = Record<string, number | string>;
+export declare type StringEnum = Record<string, string>;
 export interface CreatedUpdated {
     created: number;
     updated: number;

package/dist-esm/enum.util.js

@@ -0,0 +1,83 @@
+/**
+ * Returns all number keys of a number-enum.
+ */
+export function _numberEnumKeys(en) {
+    return Object.values(en).filter(k => typeof k === 'string');
+}
+/**
+ * Returns all number values of a number-enum.
+ */
+export function _numberEnumValues(en) {
+    return Object.values(en).filter(k => typeof k === 'number');
+}
+/**
+ * Returns all string keys of a string-enum.
+ */
+export function _stringEnumKeys(en) {
+    return Object.keys(en);
+}
+/**
+ * Returns all string values of a string-enum.
+ */
+export function _stringEnumValues(en) {
+    // filtering here is unnecessary, but works as a safety in case Number-enum is passed
+    return Object.values(en).filter(k => typeof k === 'string');
+}
+/**
+ * Returns all number-enum "entries", where entry is a tuple of [key, value],
+ * where key is a String key, value is a Number value, typed as Enum itself.
+ *
+ * Doesn't work on String-enums!
+ */
+export function _numberEnumEntries(en) {
+    return Object.values(en)
+        .filter(k => typeof k === 'string')
+        .map(k => [k, en[k]]);
+}
+/**
+ * Returns all string-enum "entries", where entry is a tuple of [key, value],
+ * where key is a String key, value is a String value, typed as Enum itself.
+ *
+ * Doesn't work on Number-enums!
+ */
+export function _stringEnumEntries(en) {
+    return Object.keys(en).map(k => [k, en[k]]);
+}
+/**
+ * Allows to return a Number enum value (typed as Enum itself) based on it's String key.
+ * e.g:
+ * const v = SomeEnum['stringValue']
+ * // v is of type SomeEnum, which is of type Number
+ *
+ * Throws if value is not found!
+ */
+export function _numberEnumInverse(en, v) {
+    const r = en[v];
+    if (!r)
+        throw new Error(`enumInverse value not found for: ${v}`);
+    return r;
+}
+/**
+ * _enumInverse, but allows to get/return undefined output.
+ */
+export function _numberEnumInverseNullable(en, v) {
+    return en[v];
+}
+/**
+ * Takes number or string enum input, returns normalized Enum output.
+ * Only works for number enums.
+ *
+ * Throws if value is not found!
+ */
+export function _numberEnumNormalize(en, v) {
+    const r = _numberEnumNormalizeNullable(en, v);
+    if (!r || !en[r])
+        throw new Error(`enumNormalize value not found for: ${v}`);
+    return r;
+}
+/**
+ * Same as _enumNormalize, but allows to return undefined values.
+ */
+export function _numberEnumNormalizeNullable(en, v) {
+    return typeof v === 'string' ? en[v] : v;
+}

package/dist-esm/index.js

@@ -15,6 +15,7 @@ export * from './decorators/retry.decorator';
 export * from './decorators/timeout.decorator';
 export * from './error/app.error';
 export * from './error/assert';
+export * from './enum.util';
 export * from './error/error.util';
 import { ErrorMode } from './error/errorMode';
 export * from './error/http.error';

package/package.json

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

package/src/enum.util.ts

@@ -0,0 +1,98 @@
+import { NumberEnum, StringEnum } from './types'
+
+/**
+ * Returns all number keys of a number-enum.
+ */
+export function _numberEnumKeys(en: NumberEnum): string[] {
+  return Object.values(en).filter(k => typeof k === 'string') as string[]
+}
+
+/**
+ * Returns all number values of a number-enum.
+ */
+export function _numberEnumValues(en: NumberEnum): number[] {
+  return Object.values(en).filter(k => typeof k === 'number') as number[]
+}
+
+/**
+ * Returns all string keys of a string-enum.
+ */
+export function _stringEnumKeys(en: StringEnum): string[] {
+  return Object.keys(en)
+}
+
+/**
+ * Returns all string values of a string-enum.
+ */
+export function _stringEnumValues(en: StringEnum): string[] {
+  // filtering here is unnecessary, but works as a safety in case Number-enum is passed
+  return Object.values(en).filter(k => typeof k === 'string')
+}
+
+/**
+ * Returns all number-enum "entries", where entry is a tuple of [key, value],
+ * where key is a String key, value is a Number value, typed as Enum itself.
+ *
+ * Doesn't work on String-enums!
+ */
+export function _numberEnumEntries<T extends NumberEnum>(en: T): [k: string, v: T[keyof T]][] {
+  return Object.values(en)
+    .filter(k => typeof k === 'string')
+    .map(k => [k, en[k]]) as any
+}
+
+/**
+ * Returns all string-enum "entries", where entry is a tuple of [key, value],
+ * where key is a String key, value is a String value, typed as Enum itself.
+ *
+ * Doesn't work on Number-enums!
+ */
+export function _stringEnumEntries<T extends StringEnum>(en: T): [k: string, v: T[keyof T]][] {
+  return Object.keys(en).map(k => [k, en[k]]) as any
+}
+
+/**
+ * Allows to return a Number enum value (typed as Enum itself) based on it's String key.
+ * e.g:
+ * const v = SomeEnum['stringValue']
+ * // v is of type SomeEnum, which is of type Number
+ *
+ * Throws if value is not found!
+ */
+export function _numberEnumInverse<T extends NumberEnum>(en: T, v: string): T[keyof T] {
+  const r = en[v as keyof T] as any
+  if (!r) throw new Error(`enumInverse value not found for: ${v}`)
+  return r
+}
+
+/**
+ * _enumInverse, but allows to get/return undefined output.
+ */
+export function _numberEnumInverseNullable<T extends NumberEnum>(
+  en: T,
+  v: string | undefined,
+): T[keyof T] | undefined {
+  return en[v as keyof T]
+}
+
+/**
+ * Takes number or string enum input, returns normalized Enum output.
+ * Only works for number enums.
+ *
+ * Throws if value is not found!
+ */
+export function _numberEnumNormalize<T extends NumberEnum>(en: T, v: string | number): T[keyof T] {
+  const r = _numberEnumNormalizeNullable(en, v)
+  if (!r || !en[r as keyof T]) throw new Error(`enumNormalize value not found for: ${v}`)
+  return r
+}
+
+/**
+ * Same as _enumNormalize, but allows to return undefined values.
+ */
+export function _numberEnumNormalizeNullable<T extends NumberEnum>(
+  en: T,
+  v: string | number | undefined,
+): T[keyof T] | undefined {
+  return typeof v === 'string' ? en[v as keyof T] : (v as any)
+}

package/src/index.ts

@@ -20,6 +20,7 @@ export * from './decorators/retry.decorator'
 export * from './decorators/timeout.decorator'
 export * from './error/app.error'
 export * from './error/assert'
+export * from './enum.util'
 import {
   Admin401ErrorData,
   Admin403ErrorData,
@@ -117,6 +118,9 @@ import {
   Predicate,
   PromiseMap,
   AnyObject,
+  AnyEnum,
+  NumberEnum,
+  StringEnum,
   AnyFunction,
   Reviver,
   SavedDBEntity,
@@ -217,6 +221,9 @@ export type {
   StringMap,
   PromiseMap,
   AnyObject,
+  AnyEnum,
+  NumberEnum,
+  StringEnum,
   AnyFunction,
   ValuesOf,
   ValueOf,

package/src/types.ts

@@ -24,6 +24,10 @@ export interface PromiseMap {
  */
 export type AnyObject = Record<string, any>
 
+export type AnyEnum = NumberEnum
+export type NumberEnum = Record<string, number | string>
+export type StringEnum = Record<string, string>
+
 export interface CreatedUpdated {
   created: number
   updated: number