@naturalcycles/js-lib 14.128.1 → 14.130.0

package/src/decorators/memo.util.ts

@@ -10,15 +10,15 @@ export const jsonMemoSerializer: MemoSerializer = args => {
 }
 
 export interface MemoCache<KEY = any, VALUE = any> {
-  has(k: KEY): boolean
-  get(k: KEY): VALUE | Error | undefined
-  set(k: KEY, v: VALUE | Error): void
+  has: (k: KEY) => boolean
+  get: (k: KEY) => VALUE | Error | undefined
+  set: (k: KEY, v: VALUE | Error) => void
 
   /**
    * Clear is only called when `.dropCache()` is called.
    * Otherwise the Cache is "persistent" (never cleared).
    */
-  clear(): void
+  clear: () => void
 }
 
 export interface AsyncMemoCache<KEY = any, VALUE = any> {
@@ -29,14 +29,14 @@ export interface AsyncMemoCache<KEY = any, VALUE = any> {
    * This also means that you CANNOT store `undefined` value in the Cache, as it'll be treated as a MISS.
    * You CAN store `null` value instead, it will be treated as a HIT.
    */
-  get(k: KEY): Promisable<VALUE | Error | undefined>
-  set(k: KEY, v: VALUE | Error): Promisable<void>
+  get: (k: KEY) => Promisable<VALUE | Error | undefined>
+  set: (k: KEY, v: VALUE | Error) => Promisable<void>
 
   /**
    * Clear is only called when `.dropCache()` is called.
    * Otherwise the Cache is "persistent" (never cleared).
    */
-  clear(): Promisable<void>
+  clear: () => Promisable<void>
 }
 
 // SingleValueMemoCache and ObjectMemoCache are example-only, not used in production code

package/src/error/app.error.ts

@@ -12,8 +12,8 @@ import type { ErrorData } from './error.model'
 export class AppError<DATA_TYPE extends ErrorData = ErrorData> extends Error {
   data!: DATA_TYPE
 
-  constructor(message: string, data = {} as DATA_TYPE) {
-    super(message)
+  constructor(message: string, data = {} as DATA_TYPE, opt?: ErrorOptions) {
+    super(message, opt)
 
     Object.defineProperty(this, 'name', {
       value: this.constructor.name,

package/src/error/assert.ts

@@ -123,8 +123,4 @@ export function _assertTypeOf<T>(v: any, expectedType: string, message?: string)
   }
 }
 
-export class AssertionError extends AppError {
-  constructor(message: string, data = {} as ErrorData) {
-    super(message, data)
-  }
-}
+export class AssertionError extends AppError {}

package/src/error/error.model.ts

@@ -76,6 +76,14 @@ export interface Admin403ErrorData extends HttpErrorData {
   adminPermissionsRequired: string[]
 }
 
+// export interface ErrorLike {
+//   name: string
+//   message: string
+//   stack?: string
+//   data?: any
+//   cause?: any
+// }
+
 /**
  * Portable object that represents Error.
  * Has extendable generic `data` property.
@@ -114,6 +122,8 @@ export interface ErrorObject<DATA_TYPE extends ErrorData = ErrorData> {
    * It's non-optional, to save some null-checks.
    */
   data: DATA_TYPE
+
+  cause?: any
 }
 
 /**

package/src/error/error.util.ts

@@ -1,11 +1,4 @@
-import type {
-  ErrorData,
-  ErrorObject,
-  HttpErrorData,
-  HttpErrorResponse,
-  StringifyAnyOptions,
-  Class,
-} from '..'
+import type { ErrorData, ErrorObject, HttpErrorData, HttpErrorResponse, Class } from '..'
 import { AppError, _jsonParseIfPossible, _stringifyAny } from '..'
 
 /**
@@ -20,7 +13,6 @@ export function _anyToError<ERROR_TYPE extends Error = Error>(
   o: any,
   errorClass: Class<ERROR_TYPE> = Error as any,
   errorData?: ErrorData,
-  opt?: StringifyAnyOptions,
 ): ERROR_TYPE {
   let e: ERROR_TYPE
 
@@ -29,8 +21,8 @@ export function _anyToError<ERROR_TYPE extends Error = Error>(
   } else {
     // If it's an instance of Error, but ErrorClass is something else (e.g AppError) - it'll be "repacked" into AppError
 
-    const errorObject = _isErrorObject(o) ? o : _anyToErrorObject(o, {}, opt)
-    e = _errorObjectToError(errorObject, errorClass) as any
+    const errorObject = _anyToErrorObject(o)
+    e = _errorObjectToError(errorObject, errorClass)
   }
 
   if (errorData) {
@@ -52,12 +44,11 @@ export function _anyToError<ERROR_TYPE extends Error = Error>(
 export function _anyToErrorObject<DATA_TYPE extends ErrorData = ErrorData>(
   o: any,
   errorData?: Partial<DATA_TYPE>,
-  opt?: StringifyAnyOptions,
 ): ErrorObject<DATA_TYPE> {
   let eo: ErrorObject<DATA_TYPE>
 
   if (o instanceof Error) {
-    eo = _errorToErrorObject<DATA_TYPE>(o, opt?.includeErrorStack ?? true)
+    eo = _errorToErrorObject<DATA_TYPE>(o)
   } else {
     o = _jsonParseIfPossible(o)
 
@@ -70,10 +61,7 @@ export function _anyToErrorObject<DATA_TYPE extends ErrorData = ErrorData>(
       // so, fair to return `data: {}` in the end
       // Also we're sure it includes no "error name", e.g no `Error: ...`,
       // so, fair to include `name: 'Error'`
-      const message = _stringifyAny(o, {
-        includeErrorData: true, // cause we're returning an ErrorObject, not a stringified error (yet)
-        ...opt,
-      })
+      const message = _stringifyAny(o)
 
       eo = {
         name: 'Error',
@@ -89,16 +77,16 @@ export function _anyToErrorObject<DATA_TYPE extends ErrorData = ErrorData>(
 
 export function _errorToErrorObject<DATA_TYPE extends ErrorData = ErrorData>(
   e: AppError<DATA_TYPE> | Error,
-  includeErrorStack = true,
 ): ErrorObject<DATA_TYPE> {
   const obj: ErrorObject<DATA_TYPE> = {
     name: e.name,
     message: e.message,
     data: { ...(e as any).data }, // empty by default
+    stack: e.stack,
   }
 
-  if (includeErrorStack) {
-    obj.stack = e.stack
+  if (e.cause) {
+    obj.cause = _anyToErrorObject(e.cause)
   }
 
   return obj
@@ -138,6 +126,15 @@ export function _errorObjectToError<DATA_TYPE extends ErrorData, ERROR_TYPE exte
     })
   }
 
+  if (o.cause) {
+    Object.defineProperty(err, 'cause', {
+      value: o.cause,
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    })
+  }
+
   return err
 }
 
@@ -159,10 +156,18 @@ export function _isHttpErrorObject(o: any): o is ErrorObject<HttpErrorData> {
  */
 export function _isErrorObject(o: any): o is ErrorObject {
   return (
-    !!o && typeof o.name === 'string' && typeof o.message === 'string' && typeof o.data === 'object'
+    !!o &&
+    typeof o === 'object' &&
+    typeof o.name === 'string' &&
+    typeof o.message === 'string' &&
+    typeof o.data === 'object'
   )
 }
 
+// export function _isErrorLike(o: any): o is ErrorLike {
+//   return !!o && typeof o === 'object' && typeof o.name === 'string' && typeof o.message === 'string'
+// }
+
 /**
  * Convenience function to safely add properties to Error's `data` object
  * (even if it wasn't previously existing)

package/src/error/errorMode.ts

@@ -10,7 +10,7 @@ export enum ErrorMode {
   THROW_IMMEDIATELY = 'THROW_IMMEDIATELY',
 
   /**
-   * Don't throw on errors, but collect them and throw as AggregatedError in the end.
+   * Don't throw on errors, but collect them and throw as AggregateError in the end.
    */
   THROW_AGGREGATED = 'THROW_AGGREGATED',
 

package/src/error/http.error.ts

@@ -7,7 +7,7 @@ import type { HttpErrorData } from './error.model'
 export class HttpError<
   DATA_TYPE extends HttpErrorData = HttpErrorData,
 > extends AppError<DATA_TYPE> {
-  constructor(message: string, data: DATA_TYPE) {
-    super(message, data)
+  constructor(message: string, data: DATA_TYPE, opt?: ErrorOptions) {
+    super(message, data, opt)
   }
 }

package/src/error/tryCatch.ts

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

package/src/http/fetcher.ts

@@ -219,15 +219,12 @@ export class Fetcher {
                 res.body = text
                 res.body = JSON.parse(text, req.jsonReviver)
               } catch (err) {
+                const { message } = _anyToError(err)
+                res.err = new HttpError([signature, message].join('\n'), {
+                  httpStatusCode: 0,
+                  url: req.url,
+                })
                 res.ok = false
-                res.err = _anyToError(
-                  err,
-                  HttpError,
-                  _filterNullishValues({
-                    httpStatusCode: 0,
-                    url: req.url,
-                  }),
-                )
               }
             } else {
               // Body had a '' (empty string)

package/src/index.ts

@@ -37,7 +37,6 @@ export * from './object/deepEquals'
 export * from './object/object.util'
 export * from './object/sortObject'
 export * from './object/sortObjectDeep'
-export * from './promise/AggregatedError'
 export * from './promise/pDefer'
 export * from './promise/pDelay'
 export * from './promise/pFilter'
@@ -59,7 +58,6 @@ export * from './is.util'
 export * from './typeFest'
 export * from './types'
 export * from './unit/size.util'
-import { is } from './vendor/is'
 export * from './log/commonLogger'
 export * from './string/safeJsonStringify'
 export * from './promise/pQueue'
@@ -77,5 +75,10 @@ export * from './datetime/timeInterval'
 export * from './http/http.model'
 export * from './http/fetcher'
 export * from './http/fetcher.model'
+export * from './zod/zod.util'
+export * from './zod/zod.shared.schemas'
+import { z, ZodSchema, ZodError, ZodIssue } from 'zod'
+import { is } from './vendor/is'
 
-export { is }
+export { is, z, ZodSchema, ZodError }
+export type { ZodIssue }

package/src/json-schema/jsonSchemaBuilder.ts

@@ -26,7 +26,7 @@ import type {
 /* eslint-disable id-blacklist, @typescript-eslint/explicit-module-boundary-types */
 
 export interface JsonSchemaBuilder<T = unknown> {
-  build(): JsonSchema<T>
+  build: () => JsonSchema<T>
 }
 
 /**

package/src/promise/pDefer.ts

@@ -2,8 +2,8 @@
  * Similar to Deferred object, which is also a promise itself (instead of deferred.promise).
  */
 export interface DeferredPromise<T = void> extends Promise<T> {
-  resolve(a?: T): void
-  reject(e?: Error): void
+  resolve: (a?: T) => void
+  reject: (e?: Error) => void
 }
 
 /* eslint-disable @typescript-eslint/promise-function-async */

package/src/promise/pMap.ts

@@ -9,7 +9,6 @@ Improvements:
 
 import type { AbortableAsyncMapper } from '..'
 import { END, ErrorMode, SKIP } from '..'
-import { AggregatedError } from './AggregatedError'
 
 export interface PMapOptions {
   /**
@@ -93,7 +92,7 @@ export async function pMap<IN, OUT>(
     }
 
     if (errors.length) {
-      throw new AggregatedError(errors, ret)
+      throw new AggregateError(errors, `pMap resulted in ${errors.length} error(s)`)
     }
 
     return ret as OUT[]
@@ -115,7 +114,7 @@ export async function pMap<IN, OUT>(
     })
 
     if (errors.length) {
-      throw new AggregatedError(errors, ret)
+      throw new AggregateError(errors, `pMap resulted in ${errors.length} error(s)`)
     }
 
     return ret as OUT[]
@@ -135,7 +134,7 @@ export async function pMap<IN, OUT>(
           isSettled = true
           const r = ret.filter(r => r !== SKIP) as OUT[]
           if (errors.length) {
-            reject(new AggregatedError(errors, r))
+            reject(new AggregateError(errors, `pMap resulted in ${errors.length} error(s)`))
           } else {
             resolve(r)
           }

package/src/promise/pRetry.ts

@@ -43,7 +43,7 @@ export interface PRetryOptions {
    *
    * @default () => true
    */
-  predicate?(err: Error, attempt: number, maxAttempts: number): boolean
+  predicate?: (err: Error, attempt: number, maxAttempts: number) => boolean
 
   /**
    * Log the first attempt (which is not a "retry" yet).

package/src/promise/pTimeout.ts

@@ -23,7 +23,7 @@ export interface PTimeoutOptions {
    * err (which is TimeoutError) is passed as an argument for convenience, so it can
    * be logged or such. You don't have to consume it in any way though.
    */
-  onTimeout?(err: TimeoutError): any
+  onTimeout?: (err: TimeoutError) => any
 
   /**
    * Defaults to true.

package/src/string/pupa.ts

@@ -31,7 +31,7 @@ export interface PupaOptions {
   /**
    * Performs arbitrary operation for each interpolation. If the returned value was `undefined`, it behaves differently depending on the `ignoreMissing` option. Otherwise, the returned value will be interpolated into a string (and escaped when double-braced) and embedded into the template.
    */
-  transform?(data: { value: any; key: string }): unknown
+  transform?: (data: { value: any; key: string }) => unknown
 }
 
 /**

package/src/string/readingTime.ts

@@ -16,7 +16,7 @@ export interface ReadingTimeOptions {
    * A function that returns a boolean value depending on if a character is considered as a word bound.
    * Default: spaces, new lines and tabs
    */
-  wordBound?(char: string): boolean
+  wordBound?: (char: string) => boolean
   /**
    * Default 200
    */

package/src/string/stringifyAny.ts

@@ -3,6 +3,8 @@ import type { Reviver } from '../types'
 import { _jsonParseIfPossible } from './json.util'
 import { _safeJsonStringify } from './safeJsonStringify'
 
+const supportsAggregateError = typeof globalThis.AggregateError === 'function'
+
 let globalStringifyFunction: JsonStringifyFunction = _safeJsonStringify
 
 /**
@@ -45,6 +47,13 @@ export interface StringifyAnyOptions {
    */
   includeErrorStack?: boolean
 
+  /**
+   * Set to false to skip including Error.cause.
+   *
+   * @default true
+   */
+  includeErrorCause?: boolean
+
   /**
    * Allows to pass custom "stringify function".
    * E.g in Node.js you can pass `util.inspect` instead.
@@ -91,6 +100,7 @@ export function _stringifyAny(obj: any, opt: StringifyAnyOptions = {}): string {
   }
 
   if (obj instanceof Error || _isErrorObject(obj)) {
+    const { includeErrorCause = true } = opt
     //
     // Error or ErrorObject
     //
@@ -100,7 +110,7 @@ export function _stringifyAny(obj: any, opt: StringifyAnyOptions = {}): string {
     // if (obj?.name === 'Error') {
     //   s = obj.message
     // }
-    s = [obj.name, obj.message].join(': ')
+    s = [obj.name, obj.message].filter(Boolean).join(': ')
 
     if (opt.includeErrorStack && obj.stack) {
       // Here we're using the previously-generated "title line" (e.g "Error: some_message"),
@@ -128,6 +138,18 @@ export function _stringifyAny(obj: any, opt: StringifyAnyOptions = {}): string {
       // Error that has no `data`, but has `code` property
       s = [s, `code: ${(obj as any).code}`].join('\n')
     }
+
+    if (supportsAggregateError && obj instanceof AggregateError && obj.errors.length) {
+      s = [
+        s,
+        `${obj.errors.length} error(s):`,
+        ...obj.errors.map((err, i) => `${i + 1}. ${_stringifyAny(err, opt)}`),
+      ].join('\n')
+    }
+
+    if (obj.cause && includeErrorCause) {
+      s = s + '\ncaused by: ' + _stringifyAny(obj.cause, opt)
+    }
   } else if (typeof obj === 'string') {
     //
     // String

package/src/zod/zod.shared.schemas.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod'
+
+export const TS_2500 = 16725225600 // 2500-01-01
+export const TS_2000 = 946684800 // 2000-01-01
+
+export const zUnixTimestamp = z
+  .number()
+  .int()
+  .min(0)
+  .max(TS_2500, 'Must be a UnixTimestamp number')
+  .describe('UnixTimestamp')
+export const zUnixTimestamp2000 = z
+  .number()
+  .int()
+  .min(TS_2000)
+  .max(TS_2500, 'Must be a UnixTimestamp number after 2000-01-01')
+  .describe('UnixTimestamp2000')
+export const zUnixTimestampMillis = z
+  .number()
+  .int()
+  .min(0)
+  .max(TS_2500 * 1000, 'Must be a UnixTimestampMillis number')
+  .describe('UnixTimestampMillis')
+export const zUnixTimestampMillis2000 = z
+  .number()
+  .int()
+  .min(TS_2000 * 1000)
+  .max(TS_2500 * 1000, 'Must be a UnixTimestampMillis number after 2000-01-01')
+  .describe('UnixTimestampMillis2000')
+
+export const zSemVer = z
+  .string()
+  .regex(/^[0-9]+\.[0-9]+\.[0-9]+$/, 'Must be a SemVer string')
+  .describe('SemVer')
+
+export const zIsoDateString = z
+  .string()
+  .refine(v => {
+    return /^\d{4}-\d{2}-\d{2}$/.test(v)
+  }, 'Must be an IsoDateString')
+  .describe('IsoDateString')
+
+export const zEmail = z
+  .string()
+  .trim()
+  .email()
+  .transform(s => s.toLowerCase())
+  .describe('Email')
+
+export const BASE62_REGEX = /^[a-zA-Z0-9]+$/
+export const BASE64_REGEX = /^[A-Za-z0-9+/]+={0,2}$/
+export const BASE64URL_REGEX = /^[\w-/]+$/
+export const zBase62 = z
+  .string()
+  .regex(BASE62_REGEX, 'Must be a base62 string')
+  .describe('Base62String')
+export const zBase64 = z
+  .string()
+  .regex(BASE64_REGEX, 'Must be a base64 string')
+  .describe('Base64String')
+export const zBase64Url = z
+  .string()
+  .regex(BASE64URL_REGEX, 'Must be a base64url string')
+  .describe('Base64UrlString')
+
+export const JWT_REGEX = /^[\w-]+\.[\w-]+\.[\w-]+$/
+export const zJwt = z.string().regex(JWT_REGEX, 'Must be a JWT string').describe('JWTString')
+
+export const zId = z
+  .string()
+  .regex(/^[a-zA-Z0-9_]{6,64}$/, 'Must be an id string')
+  .describe('IdString')
+export const zIdBase62 = z
+  .string()
+  .regex(/^[a-zA-Z0-9]{8,64}$/, 'Must be a base62 id string')
+  .describe('Base62Id')
+export const zIdBase64 = z
+  .string()
+  .regex(/^[A-Za-z0-9+/]{6,62}={0,2}$/, 'Must be a base64 id string')
+  .describe('Base64Id')
+export const zIdBase64Url = z
+  .string()
+  .regex(/^[\w-/]{8,64}$/, 'Must be a base64url id string')
+  .describe('Base64UrlId')
+
+/**
+ * "Slug" - a valid URL, filename, etc.
+ */
+export const zSlug = z
+  .string()
+  .regex(/^[a-z0-9-]{1,255}$/, 'Must be a slug string')
+  .describe('Slug')
+
+export const zBaseDBEntity = z
+  .object({
+    id: z.string().optional(),
+    created: zUnixTimestamp2000.optional(),
+    updated: zUnixTimestamp2000.optional(),
+  })
+  .describe('BaseDBEntity')
+
+export const zSavedDBEntity = zBaseDBEntity.required().describe('SavedDBEntity')

package/src/zod/zod.util.ts

@@ -0,0 +1,77 @@
+import { ZodError, ZodSchema, ZodIssue } from 'zod'
+import { _stringifyAny } from '../string/stringifyAny'
+
+export interface ZodErrorResult<T> {
+  success: false
+  data?: T
+  error: ZodValidationError<T>
+}
+
+export interface ZodSuccessResult<T> {
+  success: true
+  data: T
+  error?: ZodValidationError<T>
+}
+
+export function zIsValid<T>(value: T, schema: ZodSchema<T>): boolean {
+  const { success } = schema.safeParse(value)
+  return success
+}
+
+export function zValidate<T>(value: T, schema: ZodSchema<T>): T {
+  const r = zSafeValidate(value, schema)
+  if (r.success) {
+    return r.data
+  }
+
+  throw r.error
+}
+
+export function zSafeValidate<T>(
+  value: T,
+  schema: ZodSchema<T>,
+  // objectName?: string,
+): ZodSuccessResult<T> | ZodErrorResult<T> {
+  const r = schema.safeParse(value)
+  if (r.success) {
+    return r
+  }
+
+  return {
+    success: false,
+    error: new ZodValidationError<T>(r.error.issues, value, schema),
+  }
+}
+
+export class ZodValidationError<T> extends ZodError<T> {
+  constructor(issues: ZodIssue[], public value: T, public schema: ZodSchema<T>) {
+    super(issues)
+  }
+
+  override get message(): string {
+    return this.annotate()
+  }
+
+  annotate(): string {
+    let objectTitle = this.schema.description
+
+    if (typeof this.value === 'object' && this.value) {
+      const objectName = this.schema.description || this.value.constructor?.name
+      const objectId = (this.value as any)['id'] as string
+      objectTitle = [objectName, objectId].filter(Boolean).join('.')
+    }
+
+    objectTitle ||= 'data'
+
+    return [
+      `Invalid ${objectTitle}`,
+      '',
+      'Input:',
+      _stringifyAny(this.value),
+      this.issues.length > 1 ? `\n${this.issues.length} issues:` : '',
+      ...this.issues.slice(0, 100).map(i => {
+        return [i.path.join('.'), i.message].filter(Boolean).join(': ')
+      }),
+    ].join('\n')
+  }
+}

package/dist/promise/AggregatedError.d.ts

@@ -1,10 +0,0 @@
-/**
- * Error that aggregates a number of other errors.
- * .errors contain raw original errors to be accessed if needed.
- * .results contain the results of some batch operation (if needed).
- */
-export declare class AggregatedError<RESULT = any> extends Error {
-    errors: Error[];
-    results: RESULT[];
-    constructor(errors: Error[], results?: RESULT[]);
-}

package/dist/promise/AggregatedError.js

@@ -1,34 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AggregatedError = void 0;
-/**
- * Error that aggregates a number of other errors.
- * .errors contain raw original errors to be accessed if needed.
- * .results contain the results of some batch operation (if needed).
- */
-class AggregatedError extends Error {
-    constructor(errors, results = []) {
-        const message = [
-            `${errors.length} errors:`,
-            ...errors.map((e, i) => `${i + 1}. ${e.message}`),
-        ].join('\n');
-        super(message);
-        this.errors = errors;
-        this.results = results;
-        Object.defineProperty(this, 'name', {
-            value: this.constructor.name,
-            configurable: true,
-        });
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, this.constructor);
-        }
-        else {
-            Object.defineProperty(this, 'stack', {
-                value: new Error().stack,
-                writable: true,
-                configurable: true,
-            });
-        }
-    }
-}
-exports.AggregatedError = AggregatedError;