@naturalcycles/js-lib 15.19.0 → 15.21.0

package/dist/validation/validation.d.ts

@@ -1,30 +1,30 @@
 import type { AppError } from '../error/error.util.js';
-import type { ErrorDataTuple } from '../types.js';
 /**
- * Item to be validated.
- * Can be null or undefined, which allows validation function to produce an error,
- * if undefined/null are not accepted. But they might be accepted too, it depends
- * on the schema (implementation detail of the ValidationFunction).
+ * Function returns a tuple of [err, output].
  *
- * Function returns a tuple of [err, item].
- * In case of error it will be [err, null].
- * In case of success it is [null, item].
+ * If ERR is returned, it indicates that validation has failed.
+ * If ERR is null - validation has succeeded.
+ *
+ * Regardless of the Error, ValidationFunction always returns the output item.
+ *
+ * Output item may be transformed or not, depending on the implementation.
  *
  * ValidationFunction may mutate the input item or not,
  * depending on the implementation.
  *
  * @experimental
  */
-export type ValidationFunction<T, ERR extends AppError> = (item: T | null | undefined, opt?: ValidationFunctionOptions) => ErrorDataTuple<T, ERR>;
+export type ValidationFunction<T, ERR extends AppError> = (input: T, opt?: ValidationFunctionOptions) => ValidationFunctionResult<T, ERR>;
+export type ValidationFunctionResult<T, ERR extends AppError> = [err: ERR | null, output: T];
 export interface ValidationFunctionOptions {
     /**
      * E.g User
      * Used for error message printing.
      */
-    itemName?: string;
+    inputName?: string;
     /**
      * E.g `12345678` (user id).
      * Used for error message printing.
      */
-    itemId?: string;
+    inputId?: string;
 }

package/dist/zod/zod.shared.schemas.d.ts

@@ -1,3 +1,4 @@
+import type { ZodString } from 'zod';
 import { z } from 'zod';
 import type { IsoDate, UnixTimestamp, UnixTimestampMillis } from '../types.js';
 type ZodBranded<T, B> = T & Record<'_zod', Record<'output', number & B>>;
@@ -26,10 +27,23 @@ export declare const zJwt: () => z.ZodString;
  */
 export declare const zSlug: () => z.ZodString;
 export declare const zIanaTimezone: () => z.ZodEnum;
+export declare const zBaseDBEntity: () => z.ZodObject<{
+    id: ZodString;
+    created: ZodBrandedInt<UnixTimestamp>;
+    updated: ZodBrandedInt<UnixTimestamp>;
+}>;
+type BaseDBEntityZodShape = {
+    id: ZodString;
+    created: ZodBrandedInt<UnixTimestamp>;
+    updated: ZodBrandedInt<UnixTimestamp>;
+};
+declare function zDBEntity(): z.ZodObject<BaseDBEntityZodShape>;
+declare function zDBEntity<T extends z.ZodRawShape>(shape: T): z.ZodObject<BaseDBEntityZodShape & T>;
 export declare const customZodSchemas: {
     base62: () => z.ZodString;
     base64: () => z.ZodString;
     base64Url: () => z.ZodString;
+    dbEntity: typeof zDBEntity;
     email: () => z.ZodEmail;
     ianaTimezone: () => z.ZodEnum;
     isoDate: () => ZodBrandedString<IsoDate>;

package/dist/zod/zod.shared.schemas.js

@@ -54,10 +54,21 @@ export const zSlug = () => z
 export const zIanaTimezone = () => z
     // UTC is added to assist unit-testing, which uses UTC by default (not technically a valid Iana timezone identifier)
     .enum([...Intl.supportedValuesOf('timeZone'), 'UTC']);
+export const zBaseDBEntity = () => {
+    return z.object({
+        id: z.string(),
+        created: zUnixTimestamp2000(),
+        updated: zUnixTimestamp2000(),
+    });
+};
+function zDBEntity(shape) {
+    return zBaseDBEntity().extend(shape ?? {});
+}
 export const customZodSchemas = {
     base62: zBase62,
     base64: zBase64,
     base64Url: zBase64Url,
+    dbEntity: zDBEntity,
     email: zEmail,
     ianaTimezone: zIanaTimezone,
     isoDate: zIsoDate,

package/dist/zod/zod.util.d.ts

@@ -1,19 +1,10 @@
 import type { ZodError, ZodType } from 'zod';
 import type { ErrorData } from '../error/error.model.js';
 import { AppError } from '../error/error.util.js';
-export interface ZodErrorResult<T> {
-    success: false;
-    data?: T;
-    error: ZodValidationError;
-}
-export interface ZodSuccessResult<T> {
-    success: true;
-    data: T;
-    error?: ZodValidationError;
-}
+import type { ValidationFunctionResult } from '../validation/validation.js';
 export declare function zIsValid<T>(value: T, schema: ZodType<T>): boolean;
 export declare function zValidate<T>(value: T, schema: ZodType<T>): T;
-export declare function zSafeValidate<T>(value: T, schema: ZodType<T>): ZodSuccessResult<T> | ZodErrorResult<T>;
+export declare function zSafeValidate<T>(input: T, schema: ZodType<T>): ValidationFunctionResult<T, ZodValidationError>;
 export interface ZodValidationErrorData extends ErrorData {
 }
 export declare class ZodValidationError extends AppError<ZodValidationErrorData> {

package/dist/zod/zod.util.js

@@ -5,21 +5,17 @@ export function zIsValid(value, schema) {
     return success;
 }
 export function zValidate(value, schema) {
-    const r = zSafeValidate(value, schema);
-    if (r.success) {
-        return r.data;
-    }
-    throw r.error;
+    const [err, data] = zSafeValidate(value, schema);
+    if (err)
+        throw err;
+    return data;
 }
-export function zSafeValidate(value, schema) {
-    const r = schema.safeParse(value);
+export function zSafeValidate(input, schema) {
+    const r = schema.safeParse(input);
     if (r.success) {
-        return r;
+        return [null, r.data];
     }
-    return {
-        success: false,
-        error: new ZodValidationError(r.error, value, schema),
-    };
+    return [new ZodValidationError(r.error, input, schema), r.data ?? input];
 }
 export class ZodValidationError extends AppError {
     constructor(zodError, value, schema) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.19.0",
+  "version": "15.21.0",
   "dependencies": {
     "tslib": "^2",
     "zod": "^4"

package/src/string/stringify.ts

@@ -180,7 +180,11 @@ export function _stringify(obj: any, opt: StringifyOptions = {}): string {
   // Handle maxLen
   const { maxLen = 10_000 } = opt
   if (maxLen && s.length > maxLen) {
-    return _truncateMiddle(s, maxLen, `\n... ${Math.ceil(s.length / 1024)} Kb message truncated ...\n`)
+    return _truncateMiddle(
+      s,
+      maxLen,
+      `\n... ${Math.ceil(s.length / 1024)} Kb message truncated ...\n`,
+    )
   }
 
   return s

package/src/validation/validation.ts

@@ -1,15 +1,14 @@
 import type { AppError } from '../error/error.util.js'
-import type { ErrorDataTuple } from '../types.js'
 
 /**
- * Item to be validated.
- * Can be null or undefined, which allows validation function to produce an error,
- * if undefined/null are not accepted. But they might be accepted too, it depends
- * on the schema (implementation detail of the ValidationFunction).
+ * Function returns a tuple of [err, output].
  *
- * Function returns a tuple of [err, item].
- * In case of error it will be [err, null].
- * In case of success it is [null, item].
+ * If ERR is returned, it indicates that validation has failed.
+ * If ERR is null - validation has succeeded.
+ *
+ * Regardless of the Error, ValidationFunction always returns the output item.
+ *
+ * Output item may be transformed or not, depending on the implementation.
  *
  * ValidationFunction may mutate the input item or not,
  * depending on the implementation.
@@ -17,19 +16,21 @@ import type { ErrorDataTuple } from '../types.js'
  * @experimental
  */
 export type ValidationFunction<T, ERR extends AppError> = (
-  item: T | null | undefined,
+  input: T,
   opt?: ValidationFunctionOptions,
-) => ErrorDataTuple<T, ERR>
+) => ValidationFunctionResult<T, ERR>
+
+export type ValidationFunctionResult<T, ERR extends AppError> = [err: ERR | null, output: T]
 
 export interface ValidationFunctionOptions {
   /**
    * E.g User
    * Used for error message printing.
    */
-  itemName?: string
+  inputName?: string
   /**
    * E.g `12345678` (user id).
    * Used for error message printing.
    */
-  itemId?: string
+  inputId?: string
 }

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

@@ -1,3 +1,4 @@
+import type { ZodString } from 'zod'
 import { z } from 'zod'
 import type { IsoDate, UnixTimestamp, UnixTimestampMillis } from '../types.js'
 
@@ -88,10 +89,37 @@ export const zIanaTimezone = (): z.ZodEnum =>
     // UTC is added to assist unit-testing, which uses UTC by default (not technically a valid Iana timezone identifier)
     .enum([...Intl.supportedValuesOf('timeZone'), 'UTC'])
 
+export const zBaseDBEntity = (): z.ZodObject<{
+  id: ZodString
+  created: ZodBrandedInt<UnixTimestamp>
+  updated: ZodBrandedInt<UnixTimestamp>
+}> => {
+  return z.object({
+    id: z.string(),
+    created: zUnixTimestamp2000(),
+    updated: zUnixTimestamp2000(),
+  })
+}
+
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+type BaseDBEntityZodShape = {
+  id: ZodString
+  created: ZodBrandedInt<UnixTimestamp>
+  updated: ZodBrandedInt<UnixTimestamp>
+}
+
+function zDBEntity(): z.ZodObject<BaseDBEntityZodShape>
+function zDBEntity<T extends z.ZodRawShape>(shape: T): z.ZodObject<BaseDBEntityZodShape & T>
+
+function zDBEntity<T extends z.ZodRawShape>(shape?: T): z.ZodObject<BaseDBEntityZodShape & T> {
+  return zBaseDBEntity().extend(shape ?? {}) as z.ZodObject<BaseDBEntityZodShape & T>
+}
+
 export const customZodSchemas = {
   base62: zBase62,
   base64: zBase64,
   base64Url: zBase64Url,
+  dbEntity: zDBEntity,
   email: zEmail,
   ianaTimezone: zIanaTimezone,
   isoDate: zIsoDate,

package/src/zod/zod.util.ts

@@ -2,18 +2,7 @@ import type { ZodError, ZodType } from 'zod'
 import type { ErrorData } from '../error/error.model.js'
 import { AppError } from '../error/error.util.js'
 import { _stringify } from '../string/stringify.js'
-
-export interface ZodErrorResult<T> {
-  success: false
-  data?: T
-  error: ZodValidationError
-}
-
-export interface ZodSuccessResult<T> {
-  success: true
-  data: T
-  error?: ZodValidationError
-}
+import type { ValidationFunctionResult } from '../validation/validation.js'
 
 export function zIsValid<T>(value: T, schema: ZodType<T>): boolean {
   const { success } = schema.safeParse(value)
@@ -21,28 +10,22 @@ export function zIsValid<T>(value: T, schema: ZodType<T>): boolean {
 }
 
 export function zValidate<T>(value: T, schema: ZodType<T>): T {
-  const r = zSafeValidate(value, schema)
-  if (r.success) {
-    return r.data
-  }
-
-  throw r.error
+  const [err, data] = zSafeValidate(value, schema)
+  if (err) throw err
+  return data
 }
 
 export function zSafeValidate<T>(
-  value: T,
+  input: T,
   schema: ZodType<T>,
   // objectName?: string,
-): ZodSuccessResult<T> | ZodErrorResult<T> {
-  const r = schema.safeParse(value)
+): ValidationFunctionResult<T, ZodValidationError> {
+  const r = schema.safeParse(input)
   if (r.success) {
-    return r
+    return [null, r.data]
   }
 
-  return {
-    success: false,
-    error: new ZodValidationError(r.error, value, schema),
-  }
+  return [new ZodValidationError(r.error, input, schema), r.data ?? input]
 }
 
 export interface ZodValidationErrorData extends ErrorData {